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,assistantetool. streamtruepara 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 é 402insufficient_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).