Conclusões de chat

A API Chat Completions da OpenAI, para todos os modelos de texto: o mesmo pedido e a mesma resposta, o mesmo streaming, os mesmos SDKs.

Pedido

Resposta

{
  "id": "chatcmpl-AbC123...",
  "object": "chat.completion",
  "created": 1790870400,
  "model": "claude-opus-5-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here's the summary..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1204,
    "completion_tokens": 312,
    "total_tokens": 1516,
    "prompt_tokens_details": { "cached_tokens": 1024 },
    "completion_tokens_details": { "reasoning_tokens": 128 }
  }
}

• model é o modelo que respondeu. É o que pediu, a menos que o encaminhamento inteligente tenha usado uma alternativa.
• Os modelos de raciocínio podem acrescentar reasoning_content à mensagem: o raciocínio do modelo, quando este o partilha.
• usage corresponde à utilização faturada. cached_tokens são tokens de entrada lidos da cache de prompts do modelo, faturados ao preço de cache quando o modelo tem um.

Todas as respostas incluem também estes cabeçalhos:

Streaming

Com stream: true, a resposta chega como eventos enviados pelo servidor no formato de blocos da OpenAI, terminando com data: [DONE]. Todos os SDKs leem estes eventos por si.

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.zurelay.com/v1",
    api_key=os.environ["ZURELAY_API_KEY"],
)
stream = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
      {
        "role": "user",
        "content": "Write a limerick about databases."
      }
    ],
    stream=True,
    stream_options={
      "include_usage": True
    },
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

• Não é enviada qualquer resposta até o modelo produzir o primeiro token, pelo que uma nova tentativa ou a mudança para outra via passa despercebida.
• Nos períodos sem dados (enquanto o modelo raciocina entre passos), são enviadas linhas de comentário SSE (: keep-alive) a cada 15 segundos. Os clientes ignoram-nas; servem para impedir que os proxies fechem a ligação. Se o primeiro token demorar mais de 20 segundos (devido a um prompt longo ou a uma via bloqueada que está a ser substituída), o stream abre nessa altura: os cabeçalhos e os comentários de manutenção da ligação chegam enquanto espera. Cada via tem até 3 minutos para começar (5 com esforço de raciocínio elevado) antes de se tentar a seguinte, por isso defina o tempo limite do cliente para 10 minutos.
• Um stream aberto antes do primeiro token só inclui x-zurelay-model quando nenhum outro modelo pode responder (encaminhamento inteligente desativado), e um erro após a abertura chega como um evento de erro no stream (com a mesma estrutura do corpo de erro), em vez de um código de estado de erro.
• Com include_usage, o último bloco antes de [DONE] contém uma lista choices vazia e usage.

Chamada de ferramentas

Descreva as funções em tools; quando o modelo quiser usar uma, responde com tool_calls em vez de texto. Execute a função, devolva o resultado numa mensagem tool com o ID da chamada, e o modelo continua.

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.zurelay.com/v1",
    api_key=os.environ["ZURELAY_API_KEY"],
)
response = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[
      {
        "role": "user",
        "content": "What's the weather in Lisbon right now?"
      }
    ],
    tools=[
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Current weather for a city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string"
              }
            },
            "required": [
              "city"
            ]
          }
        }
      }
    ],
)
print(response.choices[0].message.content)

Saída estruturada

Peça JSON com response_format. Um json_schema obriga os modelos que o suportam a seguir o seu esquema; json_object pede qualquer JSON válido (indique-o também no prompt).

import os
from openai import OpenAI
client = OpenAI(
    base_url="https://api.zurelay.com/v1",
    api_key=os.environ["ZURELAY_API_KEY"],
)
response = client.chat.completions.create(
    model="gpt-6.1-sol",
    messages=[
      {
        "role": "user",
        "content": "Extract the people: 'Ana met Ben and Chloe in Porto.'"
      }
    ],
    response_format={
      "type": "json_schema",
      "json_schema": {
        "name": "people",
        "schema": {
          "type": "object",
          "properties": {
            "names": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "names"
          ]
        }
      }
    },
)
print(response.choices[0].message.content)

Raciocínio

Os modelos de raciocínio pensam antes de responder. Defina reasoning_effort para equilibrar rapidez e custo com profundidade: um nível mais elevado prolonga o raciocínio, demora mais tempo e usa mais tokens de saída. Cada modelo aceita os níveis documentados pelo respetivo laboratório, de none (sem raciocínio), passando por minimal, low, medium, high e xhigh (extra-alto), até max; a tabela abaixo apresenta-os. Se omitir este parâmetro, o modelo usa o nível predefinido. Funciona da mesma forma com qualquer SDK da OpenAI, e pode experimentar cada nível no Área de testes do painel.

from openai import OpenAI
client = OpenAI(base_url="https://api.zurelay.com/v1", api_key="YOUR_ZURELAY_KEY")
response = client.chat.completions.create(
    model="zurelay-auto",
    reasoning_effort="high",
    messages=[{"role": "user", "content": "How many primes are there below 1,000?"}],
)
message = response.choices[0].message
print(getattr(message, "reasoning_content", None))  # the thinking, when the model shares it
print(message.content)

Nos modelos que o partilham, o raciocínio é devolvido com a resposta em message.reasoning_content (em streaming, em delta.reasoning_content); alguns dão ao campo o nome reasoning. É faturado como tokens de saída e faz sempre parte de completion_tokens; completion_tokens_details.reasoning_tokens contabiliza-o separadamente quando o modelo fornece essa informação. Com esforço elevado, uma resposta pode demorar minutos a começar, por isso defina um tempo limite generoso no cliente (consulte Fiabilidade e tempos limite).

Níveis por modelo

Com base na documentação de cada laboratório. Um nível que o modelo não suporte é substituído pelo nível suportado mais próximo (entre dois igualmente próximos, o mais baixo; e o raciocínio só é desativado quando envia none), pelo que o mesmo pedido funciona em todos os modelos, incluindo com encaminhamento inteligente. O cabeçalho de resposta x-zurelay-reasoning-effort indica o nível usado. Uma palavra que não corresponda a um nível é rejeitada com um 400 que lista os níveis do modelo.

Raciocínio do Claude

Neste endpoint, o Claude aceita reasoning_effort como qualquer outro modelo: low, medium, high, xhigh ou max (o Opus 4.6 não tem xhigh). No formato da própria Anthropic, o Claude raciocina de forma adaptativa a um determinado nível: envie thinking: { type: "adaptive", display: "summarized" } com output_config: { effort: "xhigh" } e leia os blocos de raciocínio. Consulte Anthropic Messages.