Conclusões de chat

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

Requisição

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 você pediu, a menos que o roteamento inteligente tenha usado uma alternativa.
• Modelos de raciocínio podem adicionar reasoning_content à mensagem: o raciocínio do modelo, quando ele o compartilha.
• usage é o que você paga. cached_tokens são tokens de entrada lidos do cache de prompts do modelo, cobrados pelo preço de cache quando o modelo tem um.

Toda resposta também tem estes cabeçalhos:

Streaming

Com stream: true, a resposta chega como eventos enviados pelo servidor (SSE) no formato de chunks da OpenAI, terminando com data: [DONE]. Todo SDK lê esses eventos para você.

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)

• Nenhuma resposta é enviada até o modelo produzir o primeiro token, então uma nova tentativa ou a troca para outra rota fica invisível para você.
• Períodos sem dados (enquanto o modelo pensa entre etapas) são preenchidos com linhas de comentário SSE (: keep-alive) a cada 15 segundos. Os clientes as ignoram; elas impedem que proxies fechem a conexão. Se o primeiro token demorar mais de 20 segundos (um prompt longo ou uma rota que travou e está sendo substituída), o stream é aberto nesse momento: os cabeçalhos e comentários de keep-alive chegam enquanto você espera. Cada rota tem até 3 minutos para começar (5 com esforço de raciocínio alto) antes de tentar a próxima, então configure o timeout do seu cliente para 10 minutos.
• Um stream aberto antes do primeiro token só inclui x-zurelay-model quando nenhum outro modelo pode responder (roteamento 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 status de erro.
• Com include_usage, o último chunk antes de [DONE] tem uma lista choices vazia e o usage.

Chamada de ferramentas

Descreva funções em tools; quando o modelo quiser usar uma, ele responde com tool_calls em vez de texto. Execute a função, envie o resultado de volta como uma 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 faz com que os modelos compatíveis sigam seu esquema; json_object pede qualquer JSON válido (diga isso no seu prompt também).

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

Modelos de raciocínio pensam antes de responder. Defina reasoning_effort para equilibrar velocidade e custo com profundidade: um nível mais alto pensa por mais tempo, demora mais e usa mais tokens de saída. Cada modelo aceita os níveis documentados pelo seu laboratório, de none (sem raciocínio), passando por minimal, low, medium, high e xhigh (extra alto), até max; a tabela abaixo lista esses níveis. Se você omitir esse parâmetro, o modelo usa o padrão. Funciona da mesma forma com qualquer SDK da OpenAI, e você pode testar cada nível no Playground 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)

O raciocínio vem junto com a resposta em message.reasoning_content (em streaming, em delta.reasoning_content) nos modelos que o compartilham; alguns chamam o campo de reasoning. Ele é cobrado como tokens de saída e sempre faz parte de completion_tokens; completion_tokens_details.reasoning_tokens o contabiliza separadamente quando o modelo informa esse dado. Com esforço alto, uma resposta pode levar minutos para começar, então configure um timeout generoso no seu cliente (veja Confiabilidade e timeouts).

Níveis de cada modelo

Com base na documentação de cada laboratório. Um nível que o modelo não aceita é executado no nível aceito mais próximo (entre dois igualmente próximos, o menor; e o raciocínio só é desativado quando você envia none), então a mesma requisição funciona em qualquer modelo, inclusive com roteamento inteligente. O cabeçalho de resposta x-zurelay-reasoning-effort informa qual nível foi usado. Uma palavra que não corresponde a um nível é rejeitada com um 400 que lista os níveis do modelo.

Raciocínio do Claude

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