Plataforma

API de Uso de Contas

Balanceamento de consultas, histórico de requisições, contadores de uso, custos e chats salvos no Playground

Use endpoints de conta quando quiser conciliar gastos, mostrar o uso dentro do seu próprio produto ou exportar testes salvos do Playground.

Uso e equilíbrio

GET /v1/account/usage retorna seu saldo de crédito atual mais eventos de uso recentes da conta vinculada à chave da API.

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

Você pode filtrar por from, to, before, model, status e source. Os valores source suportados são api, playground, gpu_cloud e hosted_agents.

Cada evento de uso inclui:

CampoSignificado
sourceapi, playground, gpu_cloud ou hosted_agents
model e endpointComo se chamava. Para GPU Cloud linhas, model é o identificador SKU da GPU.
tokensEntrada, saída, cache e total de tokens. Linhas que não são faturadas por token, como eventos de runtime da GPU Cloud, retornam zero contagem de tokens e colocam detalhes de runtime em metadata.
cost.amountCréditos debitados em USD. Essa é a única fonte de verdade para o que foi cobrado neste pedido.
status, status_code, errorResultado do pedido
output_urlsURLs de mídia geradas quando presentes
metadata.agent_type / metadata.agent_name / metadata.agent_instance_idPresente chamadas de modelo de Agente Hospedado para que você possa rastrear o uso até o agente.
metadata.gpu_slug / metadata.gpu_display / metadata.seconds / metadata.price_hourlyApresente em GPU Cloud eventos de execução para que você possa conciliar o nome de exibição, o tempo de execução e a tarifa horária.
metadata.tool_usageMapa de \{tool_name: count\} quando um modelo cobrava sobretaxas por ferramenta (por exemplo, web_search, image_search, code_interpreter, web_extractor). Só está presente quando pelo menos uma ferramenta foi disparada.
metadata.list_cost / metadata.billed_cost / metadata.discount_amountSó existe quando um desconto de preço em nível de conta foi aplicado. cost.amount já reflete o valor pós-desconto; Esses campos documentam o desconto para recibos.

cost.amount é sempre o valor final debitado. O par metadata.list_cost / metadata.billed_cost é informativo. Quando um desconto é aplicado, cost.amount é igual a billed_cost. Quando nenhum desconto se aplica, nenhum dos campos é definido; Só leia cost.amount.

Para GPU Cloud eventos, use source: "gpu_cloud" mais metadata.seconds e metadata.price_hourly para relatórios em tempo real. O objeto tokens permanece na resposta para estabilidade do esquema, mas as linhas de runtime da GPU não são faturadas por token.

Exemplo de uso de ferramentas

Quando você chama um modelo que cobra sobretaxas por ferramenta (Qwen, Perplexity, MiMo, Mistral) e o modelo invoca essas ferramentas, a resposta inclui um 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}

O cost.amount já inclui as sobretaxas por ferramenta (aqui: 2 × $0.026 web_search + 1 × $0.0208 image_search + token cost). Use tool_usage para analisar quais ferramentas contribuíram.

Chats salvos no Playground

A API pública expõe conversas salvas no Playground como recursos somente de leitura.

Liste suas conversas salvas no Playground:

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

Recupere uma única conversa por ID, incluindo seu histórico completo de mensagens:

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

Salvar e excluir chats do Playground ainda acontece no painel.