
Este guia da GPT-6.2 API leva você de uma chave de API até uma requisição funcionando para gpt-6.2-sol ou gpt-6.2-astra em cURL e com o OpenAI SDK em Python, nos endpoints Responses e Chat Completions. Todo corpo de requisição segue o schema publicado pela PoYo e as notas de migração do GPT-6.2 da OpenAI em 18 de novembro de 2026. Você pode testar prompts antes na página do modelo GPT-6.2 Sol ou na página do modelo GPT-6.2 Astra.
Não conhece os modelos ainda? A visão geral da GPT-6.2 API cobre os limites e o posicionamento.
Antes de começar
Crie uma chave no painel da PoYo e mantenha-a no seu servidor:
export POYO_API_KEY="your-poyo-key"
| Formato | Endpoint | Use quando |
|---|---|---|
| Responses | POST https://api.poyo.ai/v1/responses | Código novo, function tools, entrada de imagem, esforço de raciocínio |
| Chat Completions | POST https://api.poyo.ai/v1/chat/completions | Código existente de Chat Completions, mensagens só de texto, sem ferramentas |
Toda requisição envia Authorization: Bearer $POYO_API_KEY. Os exemplos usam gpt-6.2-sol; troque por gpt-6.2-astra para usar o Astra. Os formatos de requisição são idênticos.
Três regras do guia do GPT-6.2 da OpenAI valem para todos os exemplos abaixo:
- Não envie
temperaturenemtop_p. A OpenAI diz para omiti-los, além delogprobsetop_logprobsno Chat Completions etop_logprobsno Responses. Os schemas da PoYo ainda listamtemperatureetop_ppara modelos mais antigos. - Não defina o esforço de raciocínio como
none; a API o rejeita. - Coloque as instruções estáveis em uma mensagem
developerno início doinput. O GPT-6.2 anexa asinstructionsde nível superior depois doinput, o que as tira do prefixo que pode ir para o cache.
Primeira requisição à GPT-6.2 API com cURL
curl https://api.poyo.ai/v1/responses \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6.2-sol",
"input": [
{"role": "developer", "content": "You are a code reviewer. Be specific and cite line numbers."},
{"role": "user", "content": "Review this function for race conditions: ..."}
],
"reasoning": {"effort": "medium"},
"max_output_tokens": 8000,
"store": false
}'
model e input são obrigatórios. input é uma string simples ou um array de itens com role (developer, system, user, assistant) e content. Outros campos documentados usados neste guia: reasoning, max_output_tokens, stream, store, tools, tool_choice, previous_response_id e metadata.
A resposta é um objeto Responses retornado diretamente. O texto fica em blocos output[].content[] com type: "output_text"; o status da chamada está em status; e as contagens estão em usage.input_tokens, usage.output_tokens e usage.total_tokens.
Python com o OpenAI SDK
Aponte o SDK para a PoYo:
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.poyo.ai/v1", api_key=os.environ["POYO_API_KEY"])
resp = client.responses.create(
model="gpt-6.2-sol",
input=[
{"role": "developer", "content": "You are a senior backend engineer."},
{"role": "user", "content": "Write a migration plan from Celery 4 to Celery 5."},
],
reasoning={"effort": "medium"},
max_output_tokens=8000,
)
print(resp.output_text)
print(resp.status, resp.usage)
resp.output_text é o helper do SDK que junta todos os blocos output_text. Registre resp.usage em toda chamada; a seção de custo abaixo usa esse valor.
Chat Completions para código existente
Se o seu código já usa chat.completions.create, troque o modelo e remova os campos de amostragem:
resp = client.chat.completions.create(
model="gpt-6.2-sol",
messages=[
{"role": "system", "content": "You are a senior backend engineer."},
{"role": "user", "content": "Explain the CAP theorem with one example per trade-off."},
],
max_tokens=4000,
)
print(resp.choices[0].message.content, resp.choices[0].finish_reason)
A mesma requisição em cURL:
curl https://api.poyo.ai/v1/chat/completions \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6.2-sol",
"messages": [{"role": "user", "content": "Explain vector databases in one sentence."}],
"max_tokens": 1000
}'
O schema de Chat Completions da PoYo documenta model, messages (content como string; roles system, user, assistant), max_tokens, stream, stop, n e os campos de penalidade. Ele não documenta tools, e a OpenAI diz que a chamada de ferramentas no GPT-6.2 exige Responses, então agentes devem ficar em /v1/responses.
Definir o esforço de raciocínio pela GPT-6.2 API
A OpenAI chama o campo de reasoning.effort no Responses e de reasoning_effort no Chat Completions. A referência de Responses da PoYo documenta reasoning (exemplo {"effort": "medium"}); a referência de Chat Completions ainda não lista reasoning_effort, então este guia define o esforço apenas no Responses.
| Situação | Configuração | Fonte |
|---|---|---|
| Integração nova | medium | OpenAI: "Comece com medium em uma integração nova." |
Antes era none ou minimal | low | Nota de migração do GPT-6.2 da OpenAI |
| Tarefas longas ou complexas | Um nível mais alto | OpenAI: um esforço maior "pode ajudá-lo a persistir até as verificações finais" |
none | Rejeitado | Páginas dos modelos da OpenAI |
O guia de raciocínio da OpenAI lista low, medium, high, xhigh e max entre os valores possíveis, mas diz que eles dependem do modelo. As páginas dos modelos GPT-6.2 não listam o conjunto aceito, então envie uma requisição de teste antes de fixar no código um nível acima de medium. Os tokens de raciocínio são cobrados como saída e contam para o max_output_tokens; a OpenAI os informa em usage.output_tokens_details.reasoning_tokens.
Streaming de respostas da GPT-6.2 API
Com "stream": true, a PoYo retorna text/event-stream. Cada linha data: é um JSON cujo type dá nome ao evento; o texto chega como response.output_text.delta, e response.completed traz o objeto final com usage. A PoYo não envia linhas event: separadas, e o stream termina com data: [DONE].
stream = client.responses.create(
model="gpt-6.2-sol",
input="Write a 100-word product introduction for a log search tool.",
reasoning={"effort": "low"},
max_output_tokens=2000,
stream=True,
store=False,
)
usage = None
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
elif event.type == "response.completed":
usage = event.response.usage
elif event.type == "response.failed":
raise RuntimeError(event.response)
print("\n", usage)
No Chat Completions, stream=True retorna eventos chat.completion.chunk; o texto fica em choices[0].delta.content e o último chunk traz o usage.
Entrada de imagem
O GPT-6.2 aceita imagens junto com texto. Na PoYo, envie-as ao Responses como blocos input_image com uma URL pública ou um Data URI completo (data:image/png;base64,...). A documentação da PoYo recomenda colocar o texto antes das imagens:
{
"model": "gpt-6.2-sol",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "List every service in this architecture diagram that writes to the database."},
{"type": "input_image", "image_url": "https://example.com/diagram.png"}
]
}
],
"max_output_tokens": 3000
}
Ler o usage e calcular o custo de uma requisição
Preços da PoYo por 1M de tokens: Sol $1.60 de entrada, $8 de saída, $0.08 de leitura de cache e $2 de escrita de cache; Astra $6.40, $32, $0.32 e $8 (1 crédito = $0.005).
O guia de cache da OpenAI informa as leituras de cache cobradas em usage.input_tokens_details.cached_tokens e as escritas em usage.input_tokens_details.cache_write_tokens. O schema da PoYo inclui input_tokens_details e output_tokens_details sem listar as chaves deles, então leia esses campos de forma defensiva:
PRICES = { # PoYo USD per 1M tokens: input, output, cache read, cache write
"gpt-6.2-sol": (1.60, 8.00, 0.08, 2.00),
"gpt-6.2-astra": (6.40, 32.00, 0.32, 8.00),
}
def estimate_cost_usd(model: str, usage) -> float:
p_in, p_out, p_read, p_write = PRICES[model]
details = getattr(usage, "input_tokens_details", None)
cached = getattr(details, "cached_tokens", 0) or 0
written = getattr(details, "cache_write_tokens", 0) or 0
fresh = usage.input_tokens - cached - written
return (fresh * p_in + cached * p_read + written * p_write
+ usage.output_tokens * p_out) / 1_000_000
Trate isso como uma estimativa e confira com o seu log de uso da PoYo. Todos os preços aqui são tarifas de contexto curto. A OpenAI cobra mais acima de 272K tokens de entrada, então confira a página do modelo para qualquer requisição desse tamanho. Exemplos calculados estão em Preço da GPT-6.2 API.
Erros que vale a pena tratar
| HTTP | Causa | O que fazer |
|---|---|---|
| 400 | Campo inválido (validation_error, com detalhes) | Corrija o corpo; um esforço none ou um campo não documentado pode cair aqui |
| 401 | Chave de API ausente ou inválida | Verifique o header Authorization |
| 402 | Créditos insuficientes | Recarregue antes de tentar de novo |
| 404 | Modelo desconhecido (model_not_found) | Verifique o ID: gpt-6.2-sol, gpt-6.2-astra |
| 429 | Limite de requisições atingido | Espere e tente de novo |
| 500 / 502 / 503 | Erro do servidor ou do upstream | Tente de novo com backoff exponencial |
A documentação da PoYo diz que os endpoints de LLM hoje não têm rate limit, mas trate o 429 mesmo assim. Com o OpenAI SDK, capture openai.APIStatusError e decida pelo status_code. Repita apenas 5xx e 429; um 400 vai falhar de novo até o corpo mudar. Os corpos completos estão em códigos de erro da PoYo.
Checklist antes de publicar
- Mantenha a
POYO_API_KEYno servidor; nunca a inclua em código de navegador ou de app mobile. - Remova
temperatureetop_pde todos os caminhos de requisição do GPT-6.2, incluindo funções auxiliares compartilhadas. - Sempre defina
max_output_tokens(oumax_tokens) e deixe espaço para os tokens de raciocínio dentro desse limite. - Registre
status/finish_reasone o blocousagecompleto junto com o seu próprio ID de requisição, para que respostas truncadas e picos de custo fiquem visíveis. - Coloque o contexto longo e estável na primeira mensagem
developere a pergunta que muda por último, o que dá ao cache de prompt a chance de funcionar. - Fixe o ID do modelo na configuração, para poder trocar entre
gpt-6.2-solegpt-6.2-astrasem um deploy.
Para ferramentas, streaming de chamadas de ferramentas e cache em sessões longas de agente, continue em GPT-6.2 API para agentes de programação.
Perguntas frequentes
Como chamo a GPT-6.2 API em Python?
Use o OpenAI SDK com base_url="https://api.poyo.ai/v1", sua chave da PoYo e model="gpt-6.2-sol" ou "gpt-6.2-astra" em client.responses.create.
A GPT-6.2 API suporta streaming?
Sim, nos dois endpoints. Defina stream: true; o Responses envia eventos tipados como response.output_text.delta e o Chat Completions envia eventos chat.completion.chunk. Os dois terminam com data: [DONE].
Como defino o esforço de raciocínio na GPT-6.2 API?
Envie "reasoning": {"effort": "medium"} em /v1/responses. A OpenAI recomenda começar com medium e rejeita none.
Por que minha requisição à GPT-6.2 API falha com temperature?
A OpenAI diz para omitir temperature e top_p no GPT-6.2. Remova-os e controle o tamanho da saída com max_output_tokens ou max_tokens.
Como envio uma imagem para a GPT-6.2 API?
Use /v1/responses com um bloco input_image (URL ou Data URI) depois de um bloco input_text. O schema de Chat Completions da PoYo documenta apenas conteúdo em string.