Andén

API de Uso de Cuentas

Consulta el saldo, historial de solicitudes, contadores de uso, costes y chats guardados en Playground

Usa endpoints de cuentas cuando quieras conciliar gastos, mostrar el uso dentro de tu propio producto o exportar pruebas guardadas de Playground.

Uso y equilibrio

GET /v1/account/usage devuelve tu saldo crediticio actual más eventos recientes de uso de la cuenta vinculada a la clave API.

$curl "https://api.empiriolabs.ai/v1/account/usage?limit=25" \
>  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Puedes filtrar por from, to, before, model, status y source. Los valores de source soportados son api, playground, gpu_cloud y hosted_agents.

Cada evento de uso incluye:

CampoSignificado
sourceapi, playground, gpu_cloud o hosted_agents
model y endpointAsí se llamaba. Para GPU Cloud filas, model es el identificador de SKU de la GPU.
tokensConteos de entrada, salida, caché y total de tokens. Las filas que no son facturadas por token, como los eventos de ejecución de GPU Cloud, devolven cero conteos de tokens y ponen detalles de ejecución en metadata.
cost.amountCréditos debitados en USD. Esta es la única fuente de verdad sobre lo que se acusó en esta solicitud.
status, status_code, errorResultado de la solicitud
output_urlsURLs de medios generadas cuando están presentes
metadata.agent_type / metadata.agent_name / metadata.agent_instance_idPresenta llamadas modelo de Agente Alojado para que puedas rastrear el uso hasta el agente.
metadata.gpu_slug / metadata.gpu_display / metadata.seconds / metadata.price_hourlyPresenta en GPU Cloud eventos de ejecución para poder conciliar el nombre de visualización, la duración y la tarifa por hora.
metadata.tool_usageMapa de \{tool_name: count\} cuando un modelo facturaba recargos por herramienta (por ejemplo, web_search, image_search, code_interpreter, web_extractor). Solo está presente cuando al menos una herramienta se dispara.
metadata.list_cost / metadata.billed_cost / metadata.discount_amountSolo presente cuando se aplicó un descuento de precio a nivel de cuenta. cost.amount ya refleja el importe post-descuento; Estos campos documentan el descuento por recibos.

cost.amount siempre es la cantidad final debitada. El par metadata.list_cost / metadata.billed_cost es informativo. Cuando se aplica un descuento, cost.amount equivale a billed_cost. Cuando no se aplica ningún descuento, ninguno de los campos está establecido; Acaba de leer cost.amount.

Para GPU Cloud eventos, usa source: "gpu_cloud" plus metadata.seconds y metadata.price_hourly para informes en tiempo real. El objeto tokens permanece en la respuesta para la estabilidad del esquema, pero las filas de ejecución de la GPU no se facturan por token.

Ejemplo de uso de herramientas

Cuando llamas a un modelo que factura recargos por herramienta (Qwen, Perplexity, MiMo, Mistral) y el modelo invoca esas herramientas, la respuesta incluye un mapa de tool_usage normalizado:

1{
2  "id": "...",
3  "object": "usage_event",
4  "model": "qwen3-6-plus",
5  "cost": { "amount": 0.084, "currency": "USD" },
6  "tokens": { "input": 1250, "output": 480, "total": 1730 },
7  "metadata": {
8    "tool_usage": {
9      "web_search": 2,
10      "image_search": 1
11    }
12  }
13}

El cost.amount ya incluye los recargos por herramienta (aquí: 2 × $0.026 web_search + 1 × $0.0208 image_search + token cost). Usa tool_usage para desglosar qué herramientas han contribuido.

Chats guardados en Playground

La API pública expone las conversaciones guardadas de Playground como recursos de solo lectura.

Haz una lista de tus conversaciones guardadas en Playground:

$curl "https://api.empiriolabs.ai/v1/playground/conversations" \
>  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Recupera una sola conversación por ID, incluyendo su historial completo de mensajes:

$curl "https://api.empiriolabs.ai/v1/playground/conversations/CONVERSATION_ID" \
>  -H "Authorization: Bearer $EMPIRIOLABS_API_KEY"

Guardar y eliminar chats de Playground sigue ocurriendo en el panel de control.