how-tos

Guia da GPT-6.2 API: primeiro pedido em cURL e Python, Responses e Chat Completions

Poyo.ai Team
9 min read
Share:

Guia da GPT-6.2 API: primeiro pedido em cURL e Python

Este guia da GPT-6.2 API leva-te de uma chave de API até um pedido funcional a gpt-6.2-sol ou gpt-6.2-astra em cURL e com o OpenAI SDK para Python, tanto no endpoint Responses como no Chat Completions. Todos os corpos de pedido seguem o esquema publicado pelo PoYo e as notas de migração para o GPT-6.2 da OpenAI à data de 18 de novembro de 2026. Podes testar primeiro os prompts na página do modelo GPT-6.2 Sol ou na página do modelo GPT-6.2 Astra.

Ainda não conheces os modelos? A visão geral da GPT-6.2 API explica os limites e o posicionamento.

Antes de começar

Cria uma chave no painel do PoYo e guarda-a no teu servidor:

export POYO_API_KEY="your-poyo-key"
FormatoEndpointQuando usar
ResponsesPOST https://api.poyo.ai/v1/responsesCódigo novo, ferramentas de funções, entrada de imagens, esforço de raciocínio
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsCódigo de Chat Completions já existente, mensagens só de texto, sem ferramentas

Cada pedido envia Authorization: Bearer $POYO_API_KEY. Os exemplos usam gpt-6.2-sol; substitui-o por gpt-6.2-astra para usar o Astra. As estruturas dos pedidos são idênticas.

Três regras do guia do GPT-6.2 da OpenAI aplicam-se a todos os exemplos abaixo:

  1. Não envies temperature nem top_p. A OpenAI diz para os omitir, bem como logprobs e top_logprobs no Chat Completions e top_logprobs no Responses. Os esquemas do PoYo continuam a listar temperature e top_p para modelos mais antigos.
  2. Não definas o esforço de raciocínio como none; a API rejeita-o.
  3. Coloca as instruções estáveis numa mensagem developer no início de input. O GPT-6.2 acrescenta as instructions de nível superior depois de input, o que as tira do prefixo que pode ir para a cache.

Primeiro pedido à 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 devolvido diretamente. O texto está nos blocos output[].content[] com type: "output_text"; o estado 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

Aponta o SDK para o 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. Regista resp.usage em cada chamada; a secção de custos mais abaixo usa-o.

Chat Completions para código existente

Se o teu código já usa chat.completions.create, muda o modelo e remove 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)

O mesmo pedido 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 esquema de Chat Completions do PoYo documenta model, messages (content como string; papéis system, user, assistant), max_tokens, stream, stop, n e os campos de penalização. Não documenta tools, e a OpenAI diz que as chamadas de ferramentas no GPT-6.2 exigem Responses, por isso os agentes devem usar /v1/responses.

Definir o esforço de raciocínio na GPT-6.2 API

A OpenAI chama ao campo reasoning.effort no Responses e reasoning_effort no Chat Completions. A referência de Responses do PoYo documenta reasoning (exemplo {"effort": "medium"}); a sua referência de Chat Completions ainda não inclui reasoning_effort, por isso este guia define o esforço apenas no Responses.

SituaçãoValorFonte
Integração novamediumOpenAI: "Começa com medium numa integração nova."
Antes none ou minimallowNota de migração para o GPT-6.2 da OpenAI
Tarefas longas ou complexasUm nível mais altoOpenAI: um esforço maior "pode ajudá-lo a persistir até às verificações finais"
noneRejeitadoPáginas dos modelos da OpenAI

O guia de raciocínio da OpenAI inclui low, medium, high, xhigh e max entre os valores possíveis, mas diz que dependem do modelo. As páginas dos modelos GPT-6.2 não listam o conjunto aceite, por isso envia um pedido de teste antes de fixares no código um nível acima de medium. Os tokens de raciocínio são faturados como saída e contam para max_output_tokens; a OpenAI indica-os em usage.output_tokens_details.reasoning_tokens.

Streaming de respostas da GPT-6.2 API

Com "stream": true, o PoYo devolve text/event-stream. Cada linha data: é um JSON cujo type indica o evento; o texto chega como response.output_text.delta, e response.completed traz o objeto final com usage. O 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 devolve eventos chat.completion.chunk; o texto está em choices[0].delta.content e o último chunk traz usage.

Entrada de imagens

O GPT-6.2 aceita imagens juntamente com texto. No PoYo, envia-as para o Responses como blocos input_image com um URL público ou um Data URI completo (data:image/png;base64,...). A documentação do 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 uso e calcular o custo de um pedido

Preços do PoYo por 1M de tokens: Sol $1.60 de entrada, $8 de saída, $0.08 de leitura de cache e $2 de escrita na cache; Astra $6.40, $32, $0.32 e $8 (1 crédito = $0.005).

O guia de caching da OpenAI indica as leituras de cache faturadas em usage.input_tokens_details.cached_tokens e as escritas em usage.input_tokens_details.cache_write_tokens. O esquema do PoYo inclui input_tokens_details e output_tokens_details sem listar as suas chaves, por isso lê-os 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

Trata isto como uma estimativa e confronta-a com o teu registo de uso no PoYo. Todos os preços aqui indicados são tarifas de contexto curto. A OpenAI cobra mais acima de 272K tokens de entrada, por isso consulta a página do modelo para qualquer pedido desse tamanho. Há exemplos calculados em preços da GPT-6.2 API.

Erros que vale a pena tratar

HTTPCausaO que fazer
400Campo inválido (validation_error, com detalhes)Corrige o corpo; um esforço none ou um campo não documentado podem acabar aqui
401Chave de API em falta ou inválidaVerifica o cabeçalho Authorization
402Créditos insuficientesCarrega créditos antes de tentar de novo
404Modelo desconhecido (model_not_found)Verifica o ID: gpt-6.2-sol, gpt-6.2-astra
429Limite de taxa atingidoEspera e tenta de novo
500 / 502 / 503Erro do servidor ou do fornecedor upstreamTenta de novo com backoff exponencial

A documentação do PoYo diz que os endpoints de LLM não têm, por agora, limite de taxa, mas trata o 429 na mesma. Com o OpenAI SDK, apanha openai.APIStatusError e ramifica com base em status_code. Repete apenas os 5xx e o 429; um 400 volta a falhar até o corpo mudar. Os corpos completos estão nos códigos de erro do PoYo.

Lista de verificação antes de ir para produção

  • Mantém a POYO_API_KEY do lado do servidor; nunca a incluas em código de browser ou de mobile.
  • Remove temperature e top_p de todos os caminhos de pedido ao GPT-6.2, incluindo funções auxiliares partilhadas.
  • Define sempre max_output_tokens (ou max_tokens) e deixa espaço para os tokens de raciocínio dentro desse limite.
  • Regista status / finish_reason e o bloco usage completo ao lado do teu próprio ID de pedido, para que as respostas truncadas e os picos de custo fiquem visíveis.
  • Coloca o contexto longo e estável na primeira mensagem developer e a pergunta variável no fim, o que dá ao caching de prompts a hipótese de se aplicar.
  • Fixa o ID do modelo na configuração, para poderes alternar entre gpt-6.2-sol e gpt-6.2-astra sem um deploy.

Para ferramentas, streaming de chamadas de ferramentas e caching em sessões longas de agentes, continua com GPT-6.2 API para agentes de programação.

Perguntas frequentes

Como chamo a GPT-6.2 API em Python?

Usa o OpenAI SDK com base_url="https://api.poyo.ai/v1", a tua chave 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. Define stream: true; o Responses envia eventos tipados como response.output_text.delta e o Chat Completions envia eventos chat.completion.chunk. Ambos terminam com data: [DONE].

Como defino o esforço de raciocínio da GPT-6.2 API?

Envia "reasoning": {"effort": "medium"} em /v1/responses. A OpenAI recomenda começar com medium e rejeita none.

Porque é que o meu pedido à GPT-6.2 API falha com temperature?

A OpenAI diz para omitir temperature e top_p no GPT-6.2. Remove-os e controla o comprimento da saída com max_output_tokens ou max_tokens.

Como envio uma imagem para a GPT-6.2 API?

Usa /v1/responses com um bloco input_image (URL ou Data URI) depois de um bloco input_text. O esquema de Chat Completions do PoYo documenta apenas conteúdo em string.

Share: