Uso e orçamento

O provedor cobra o consumo diretamente na sua conta. O BotoZap registra cada chamada, mede tokens quando o provedor informa e estima o custo com as tarifas que você cadastrar. Não há créditos de IA no BotoZap.

Inferências

GET /ai/inferences

Escopo agents:read

Cada linha traz purpose, point com point_label, provedor, modelo, status, outcome, measurement_status, error_code, http_status, origin com origin_explanation, tokens, estimated_cost_usd, reserved_usd e latency_ms. Em falhas, cause, consequence e suggested_action. origin indica de onde veio o modelo: purpose, inherited_proposal, customer_default, fallback, agent_version, router_config, unrecorded.

meta.summary agrega o período inteiro filtrado, não só a página: failures (código, ponto, origem, chamadas e última ocorrência) e points (chamadas, falhas, incertas, em andamento, alternativas usadas, custo e chamadas sem medição).

GET /ai/usage

Escopo agents:read

Query customer_id, from e to (padrão: mês corrente no horário de Brasília, o mesmo do orçamento; até 366 dias), agent_id e purpose opcionais. Retorna from, to, totals, series por dia (dia de Brasília) com latência p50 e p95, agents e handoff.

Orçamento

GET /ai/usage/budget

Escopo agents:read

Query customer_id. {monthly_limit_usd, mode, alarm_threshold_pct, revision, updated_at}; sem gravação, mode: "off", limite nulo, alarme em 80% e revisão 0.

PATCH /ai/usage/budget

Escopo agents:write

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "monthly_limit_usd": 200,
  "mode": "warn",
  "alarm_threshold_pct": 80,
  "expected_revision": 0
}

O mês do orçamento vira à meia-noite de Brasília (America/Sao_Paulo). Cada chamada reserva o custo máximo antes de chamar o provedor (entrada estimada e saída máxima pedida). Uma chamada que termina sem medição (erro, interrupção ou uso não informado) continua contando no limite pela reserva. Com block, só impedem novas inferências as chamadas de custo desconhecido: feitas sem preço cadastrado (sem reserva) ou transcrições por tokens sem medição completa. POST /ai/usage/rates/reprice resolve ambas. O alerta de alarm_threshold_pct só existe em warn e block.

Tarifas

GET /ai/usage/rates

Escopo agents:read

Query customer_id. Tarifas cadastradas, com revision numérica por modelo.

PUT /ai/usage/rates

Escopo agents:write

Corpo {customer_id, provider, model, input_usd_per_million, output_usd_per_million, cache_read_usd_per_million, cache_write_usd_per_million, audio_pricing?, expected_revision}. Preços de 0 a 100.000 dólares por milhão de tokens; expected_revision é 0 para um modelo novo. Preços alterados valem para novas chamadas. Informe os preços do contrato da sua chave: o BotoZap não presume tarifas.

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "provider": "openai",
  "model": "MODELO_VALIDADO_NA_CREDENCIAL",
  "input_usd_per_million": 0.4,
  "output_usd_per_million": 1.6,
  "cache_read_usd_per_million": 0.1,
  "cache_write_usd_per_million": 0,
  "expected_revision": 0
}

Tarifas de transcrição e reservas

audio_pricing é opcional. Omitir o campo preserva a tarifa de áudio existente; null remove-a.

• unit: "tokens": exige input_audio_usd_per_million, input_text_usd_per_million, output_text_usd_per_million, max_input_tokens e max_output_tokens.
• unit: "duration": exige usd_per_minute. A reserva usa a duração verificada pelo servidor.

Preços de áudio aceitam de 0 a 100.000, com até oito casas decimais. Reservas em tokens aceitam inteiros de 1 a 100.000.000: são estimativas configuradas, não limites técnicos impostos ao provedor; o custo real pode superá-las. O preço fica registrado por chamada e o consumo medido substitui a reserva. Sem preço, ou por tokens sem medição compatível, limites que interrompem chamadas bloqueiam novas inferências até a estimativa retroativa (reprice).

POST /ai/usage/rates/reprice

Escopo agents:write

Corpo {customer_id, provider, model, expected_revision, confirm: true}, com a revisão atual da tarifa (1 ou mais). Estima o custo de chamadas anteriores que ficaram sem preço, inclusive transcrições quando as unidades medidas forem compatíveis com a tarifa de áudio. Chamadas de texto sem preço que terminaram sem medição recebem a reserva do teto pedido ao provedor; transcrições por tokens sem medição completa passam a contar pela reserva configurada. Não substitui preços já registrados nem transforma um resultado incerto em custo zero. Retorna quantas chamadas foram atualizadas.

Visão geral do Agente de IA · Próxima: Referência de endpoints