Pular para o conteúdo
quebragalho/docs

Referência da API

Chat completions

POST/v1/chat/completions

No formato da OpenAI, com e sem stream. O mesmo corpo e os mesmos SDKs; só a base URL e a key mudam.

O mesmo corpo da OpenAI

SDK oficial, LangChain, fetch na mão: se monta o request da OpenAI, funciona aqui.

model
Id do catálogo, exato. Veja em Modelos.
messages
O histórico: system, user, assistant e tool.
stream
true para receber por SSE (Streaming).
max_tokens
Teto da resposta. Acima do teto do seu plano, volta 400 max_tokens_exceeds_cap.
tools
Ferramentas de função, como na OpenAI.
temperature
Amostragem, como na OpenAI.
Resposta · 200
{  "id": "chatcmpl-…",  "object": "chat.completion",  "model": "gpt-6.2-astra",  "choices": [{    "index": 0,    "message": { "role": "assistant", "content": "Bora!…" },    "finish_reason": "stop"  }],  "usage": { "prompt_tokens": 9, "completion_tokens": 38 }}

Texto chegando em pedaços

Passe stream: true e a resposta vem por Server-Sent Events, pedaço a pedaço.

text/event-stream
: heartbeatdata: {"choices":[{"delta":{"content":"Bora"}}]}data: {"choices":[{"delta":{"content":"! Me"}}]}: heartbeatdata: {"choices":[{"delta":{"content":" conta"}}]}data: {"choices":[{"delta":{},"finish_reason":"stop"}]}data: [DONE]

Linhas que começam com : são heartbeat. Ignore e não feche a conexão por causa delas. Em raciocínio longo, pode vir só heartbeat por um bom tempo antes do primeiro token.

Erro no meio do stream chega como um evento data: com o objeto error, seguido de data: [DONE].

Uma conversa por usuário final

Se o seu app atende várias pessoas, mande um ID estável por conversa. Mesma conversa, cache aproveitado, custo menor. Sem ele nada quebra; só fica mais caro.

  • Header X-QG-Conversation-ID, com o mesmo valor em todos os turnos da conversa.
  • Até 128 caracteres imprimíveis.
  • Valor inválido é ignorado, sem erro.
  • Sem ID, usamos os headers de sessão que o seu cliente já envia ou o início do prompt.
Python
client.chat.completions.create(    model="gpt-6.2-astra",    messages=history,    extra_headers={        # estável por conversa do seu usuário        "X-QG-Conversation-ID": f"u{user.id}-c{conversation.id}",    },)

Reserva antes, cobrança no fim

  • Antes de encaminhar, o saldo separa uma reserva pelo tamanho do pedido e pelo max_tokens. Se o saldo livre não cobre, a resposta é 402 insufficient_balance.
  • No fim, a cobrança é pelos tokens que o modelo usou, no preço do modelo. O resto da reserva volta para o saldo.
  • Se o pedido falhar antes da resposta, a reserva volta inteira.
  • Saldo bônus paga os modelos que aceitam bônus; os outros usam só saldo recarregado (Modelos).