PT ▾
Base URL https://api.uncensoredaiapis.com/v1Modelo uncensored
Obter chave de API
Uncensored AIGuia de migração

Rastreador de Custos de API IA: Monitore Gastos com Cabeçalhos

Você pode criar um rastreador de custos de API de IA em cerca de cinquenta linhas, porque toda resposta já informa seu saldo restante. Este guia mostra como registrar gastos por requisição, ler os endpoints de saldo e emitir um alerta antes que o crédito acabe.

Atualizado

Painéis flutuantes com um gráfico em queda e um sino de alerta âmbar, ilustrando o monitoramento de gastos de API
Cinco pedras luminosas levando a um cubo de servidor, ilustrando os passos para começar com uma API no estilo OpenAI

Pontos principais

  • Cada resposta carrega um cabeçalho X-Balance-USD com seu crédito restante.
  • GET /v1/balance e o endpoint credit_grants retornam o saldo sob demanda.
  • O custo por chamada é (entrada x 0,15 + saída x 0,50) / 1.000.000 dólares.
  • Registre em CSV e alerte quando o saldo cair abaixo de um limiar.

De onde vêm os números

Crédito pré-pago torna o rastreamento de custos simples, porque o provedor já mantém um total acumulado. Você o obtém em três lugares:

  • O cabeçalho de resposta X-Balance-USD nas chamadas de API, mostrando o que resta após a requisição.
  • GET /v1/balance, uma consulta simples de saldo.
  • GET /v1/dashboard/billing/credit_grants, a rota estilo OpenAI que ferramentas como painéis e wrappers já sabem chamar.

Além disso, cada conclusão retorna um objeto usage com contagens de tokens de prompt e conclusão. Combine tokens com os preços ($0,15 por 1M de entrada, $0,50 por 1M de saída) e você pode calcular o custo de qualquer requisição por conta própria, depois compare com a queda no saldo. Os dois valores devem coincidir. Se não coincidirem, você encontrou algo para investigar. Detalhes completos dos parâmetros estão na documentação.

Leia o cabeçalho em uma requisição

Com curl, adicione -i e observe os cabeçalhos:

curl -si https://api.uncensoredaiapis.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"uncensored","messages":[{"role":"user","content":"Say hi."}]}' \
  | grep -i "x-balance-usd"

Em Python, o SDK OpenAI expõe respostas brutas através de with_raw_response, que fornece cabeçalhos e o objeto analisado juntos:

from openai import OpenAI

client = OpenAI(base_url="https://api.uncensoredaiapis.com/v1", api_key="sk-your-key")

raw = client.chat.completions.with_raw_response.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Say hi."}],
)
resp = raw.parse()
print(raw.headers.get("x-balance-usd"), resp.usage.total_tokens)

Um pequeno registrador que registra cada chamada

Envolva suas chamadas em uma função e grave uma linha CSV cada vez. A linha tem a hora, ID da requisição, contagens de tokens, custo calculado e saldo.

import csv, time
from openai import OpenAI

client = OpenAI(base_url="https://api.uncensoredaiapis.com/v1", api_key="sk-your-key")
PRICE_IN, PRICE_OUT = 0.15, 0.50   # dollars per 1M tokens
LOG = "api_spend.csv"

def cost(usage):
    return (usage.prompt_tokens * PRICE_IN + usage.completion_tokens * PRICE_OUT) / 1_000_000

def tracked_chat(messages, tag="default"):
    raw = client.chat.completions.with_raw_response.create(
        model="uncensored", messages=messages)
    r = raw.parse()
    row = [
        time.strftime("%Y-%m-%d %H:%M:%S"),
        raw.headers.get("x-request-id"),
        tag,
        r.usage.prompt_tokens,
        r.usage.completion_tokens,
        round(cost(r.usage), 6),
        raw.headers.get("x-balance-usd"),
    ]
    with open(LOG, "a", newline="") as f:
        csv.writer(f).writerow(row)
    return r, row

O argumento tag é o truque que torna o log útil. Passe um nome de recurso como "resumos" ou "chat", e depois você pode somar o custo por tag para ver qual parte do produto gasta o dinheiro. O ID da requisição ajuda se você precisar perguntar sobre uma cobrança ou relatar um problema, pois ele identifica a chamada exata.

Verificação rápida dos cálculos

Tome uma chamada com 2.400 tokens de entrada e 600 tokens de saída:

  • Entrada: 2.400 x 0,15 / 1.000.000 = $0,00036
  • Saída: 600 x 0,50 / 1.000.000 = $0,00030
  • Total: $0,00066

Mil desses custam $0,66. Se seu CSV mostrar um saldo caindo muito mais rápido que a soma dos custos calculados, verifique se há retentativas não registradas, processos em segundo plano usando a mesma chave ou fluxos que você deixou abertos. Requisições falhas ou recusadas não são cobradas, então erros não devem afetar o saldo. Compare totais ao longo de muitas chamadas, não individuais, para que pequenas diferenças de arredondamento se equilibrem.

Chamadas em streaming e uso

Com stream: true, os números de uso chegam ao final do fluxo. Colete-os do último fragmento, então registre a linha após o fluxo ser encerrado.

def tracked_stream(messages, tag="chat"):
    usage = None
    for chunk in client.chat.completions.create(
            model="uncensored", messages=messages, stream=True):
        if chunk.choices and chunk.choices[0].delta.content:
            yield chunk.choices[0].delta.content
        usage = getattr(chunk, "usage", None) or usage
    if usage:
        with open(LOG, "a", newline="") as f:
            csv.writer(f).writerow([time.strftime("%F %T"), "", tag,
                usage.prompt_tokens, usage.completion_tokens, round(cost(usage), 6), ""])

Se você só precisa do saldo, chame GET /v1/balance após o fluxo terminar. É uma requisição barata e também funciona como uma verificação periódica de um job cron.

Somando gastos por recurso

O CSV só é útil se você o ler. Este script curto soma o custo por tag e mostra o saldo mais recente, sem pacotes extras.

import csv
from collections import defaultdict

totals, last_balance = defaultdict(float), None
with open("api_spend.csv") as f:
    for row in csv.reader(f):
        ts, req_id, tag, pin, pout, cost_usd, balance = row
        totals[tag] += float(cost_usd)
        last_balance = balance or last_balance

for tag, usd in sorted(totals.items(), key=lambda kv: -kv[1]):
    print(f"{tag:15s} ${usd:.4f}")
print("latest balance:", last_balance)

Execute diariamente e cole a saída no canal da sua equipe. Gastos invisíveis tornam-se um número que as pessoas podem discutir, e um recurso que custa dez vezes mais que os outros se destaca imediatamente. Para um orçamento aproximado, multiplique o total diário por 30 e adicione 20% de margem de segurança.

Adicione um alerta de saldo baixo

Ficar sem crédito no meio do dia tira um produto do ar, então alerte cedo. Um job cron que roda a cada 15 minutos é suficiente.

import requests

BASE = "https://api.uncensoredaiapis.com/v1"
THRESHOLD = 5.00   # dollars

r = requests.get(BASE + "/balance", headers={"Authorization": "Bearer sk-your-key"}, timeout=10)
print(r.status_code, r.text)   # inspect the JSON once to see the field name
# After you know the field name, parse it and compare with THRESHOLD,
# then post to your chat webhook or send an email.

Imprima o JSON bruto uma vez e observe-o antes de escrever o código de análise. O nome real do campo leva dez segundos para verificar, e adivinhá-lo a partir de um artigo pode quebrar o alerta silenciosamente. Escolha um limite que cubra pelo menos um dia de gasto normal, que o CSV informa: some o custo de ontem e use isso como o mínimo.

Quando o alerta disparar, recarregue. Qualquer valor inteiro de $20 a $500 funciona, com +5% de crédito a partir de $50, +10% a partir de $100 e +15% a partir de $200, e o crédito nunca expira. Para obter uma chave para o rastreador primeiro, use a página de chave de API.

Hábitos para manter o gasto previsível

  • Use uma chave por ambiente para que o tráfego de teste nunca se esconda nos números de produção.
  • Limite max_tokens em endpoints onde respostas longas não são necessárias. É opcional por padrão, então respostas ilimitadas são possíveis.
  • Limpe o histórico do chat. Tokens de entrada são mais baratos que os de saída, mas um histórico longo repetido em cada iteração se acumula.
  • Revise o total semanal por tag e procure a tag que representa mais da metade da conta.

Mais um hábito: armazene o ID da requisição com cada linha registrada. Se um número parecer errado um mês depois, você pode correspondê-lo a uma chamada específica em vez de argumentar com médias. Como requisições falhas não são cobradas, retentativas em erros não adicionam custo, mas retentativas após uma resposta bem-sucedida sim, então certifique-se de que sua lógica de retentativa dispare apenas em falhas reais. Um bug que reenvia uma solicitação bem-sucedida em loop é a causa mais comum de uma conta surpresa com qualquer API pay-per-token.

Perguntas e respostas

O cabeçalho de saldo aparece em todas as respostas?

O cabeçalho X-Balance-USD faz parte dos cabeçalhos de resposta listados para esta API. Leia-o na resposta bruta e trate um valor ausente como desconhecido.

Posso obter o custo sem registrar cada requisição?

Sim. Consulte GET /v1/balance em um agendamento e calcule a diferença entre as leituras.

Requisições falhas alteram o saldo?

Não. Requisições falhas ou recusadas não são cobradas.

Qual endpoint deve usar uma ferramenta de painel OpenAI existente?

Use a rota GET /v1/dashboard/billing/credit_grants no estilo OpenAI, que muitas ferramentas já suportam.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.