Chat Completions

O endpoint de Chat Completions é compatível com a API da OpenAI. Ele recebe uma lista de mensagens e devolve a resposta do modelo no mesmo formato chat.completion, independentemente do provedor por trás do modelo escolhido (OpenAI, Anthropic ou Google).

POST https://retrace.com.br/api/v1/chat/completions

Toda requisição exige uma chave de API enviada no header Authorization: Bearer <sua-chave>.

Requisição básica

O único campo obrigatório além de model é messages, no formato padrão { role, content } (system, user ou assistant).

curl https://retrace.com.br/api/v1/chat/completions \
  -H "Authorization: Bearer $RETRACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "messages": [
      { "role": "user", "content": "Conte-me uma piada." }
    ]
  }'

Como o endpoint é compatível com a API da OpenAI, qualquer SDK ou cliente HTTP construído para ela funciona com a Retrace bastando apontar o baseURL/base_url para https://retrace.com.br/api/v1.

A resposta segue sempre o formato chat.completion da OpenAI, mesmo quando o modelo escolhido é da Anthropic ou do Google:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-5.2",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 34, "total_tokens": 46 }
}

Escolhendo o modelo

O valor enviado em model determina como a Retrace roteia a requisição. Existem três formatos:

Modelo com fallback (padrão)

Ao enviar uma chave de modelo comum — sem sufixo nem prefixo — a Retrace trata esse modelo como âncora e, se a chamada falhar, tenta automaticamente outros modelos equivalentes em preço, contexto e capacidade (tier), na ordem mais próxima da âncora.

{
  "model": "gpt-5.2",
  "messages": [{ "role": "user", "content": "Conte-me uma piada." }]
}

A Retrace tenta no máximo 3 modelos por requisição. Um provedor é descartado do restante das tentativas depois de 2 falhas dele nessa mesma requisição, para não insistir num provedor inteiro fora do ar. Motivos de falha que disparam fallback: timeout, erro do provedor, rate limit (429) ou sobrecarga (503/529).

O pool de modelos candidatos ao fallback respeita:

• A allowlist de modelos do roteamento do workspace, se houver uma definida.
• A exigência de zero data retention, se o workspace tiver essa opção ativada.
• Suporte a tools e a reasoning_effort: se a requisição usa esses recursos, só entram no pool modelos que os suportam.

Use fallback (o padrão) sempre que a prioridade for disponibilidade — a resposta pode vir de um modelo diferente do solicitado, mas equivalente.

Modelo com strict mode

Adicione o sufixo :strict à chave do modelo para desativar o fallback. A requisição só é tentada nesse modelo exato — se ele falhar, a Retrace retorna erro imediatamente, sem tentar outro.

{
  "model": "gpt-5.2:strict",
  "messages": [{ "role": "user", "content": "Conte-me uma piada." }]
}

Use strict mode quando a aplicação depende de características específicas de um modelo (um comportamento, um preço ou uma característica de contexto) e prefere falhar a receber a resposta de um modelo diferente.

Presets

Presets agrupam modelo(s) permitidos, prompt de sistema e parâmetros de geração numa configuração nomeada, criada no painel da Retrace. Para usar um preset numa requisição, envie @preset/<slug> no campo model:

{
  "model": "@preset/suporte-tecnico",
  "messages": [{ "role": "user", "content": "Meu pedido não chegou." }]
}

O preset define seu próprio pool de modelos elegíveis (com fallback entre eles, seguindo as mesmas regras da seção anterior) — a Retrace escolhe entre eles automaticamente, sem uma âncora fixa.

Parâmetros extras e tools

Além de model e messages, a Retrace aceita os seguintes parâmetros opcionais:

* A Anthropic ignora temperature, top_p e top_k quando reasoning_effort está definido (extended thinking ativado).

Os parâmetros de geração (temperature, top_p, top_k, frequency_penalty, presence_penalty, repetition_penalty) são filtrados por provedor automaticamente: se o provedor do modelo escolhido não suportar um deles (por exemplo, top_k na OpenAI), ele é descartado silenciosamente para essa chamada, sem gerar erro. repetition_penalty atualmente não é suportado por nenhum provedor ativo.

reasoning_effort funciona diferente: ele é sempre repassado ao provedor quando definido, sem checar se o modelo escolhido suporta raciocínio. Enviar reasoning_effort para um modelo sem esse suporte resulta em erro do provedor — o que aciona fallback normalmente (modo padrão) ou falha imediata (strict mode). Modelos de entrada/custo mais baixo tipicamente não suportam raciocínio (por exemplo, gpt-5-nano e claude-haiku-4-5) — evite enviar reasoning_effort para eles.

tools segue o formato de function calling da OpenAI:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Retorna o clima atual de uma cidade",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ]
}

A Retrace traduz esse formato automaticamente para o formato nativo de tools do provedor por trás do modelo escolhido (Anthropic ou Google), então o mesmo payload de tools funciona em qualquer modelo.

O que é ignorado ao usar um preset

Quando model é @preset/<slug>, o preset assume o controle da configuração da chamada. Os seguintes campos, se enviados na requisição, não têm efeito:

• temperature, top_p, top_k, frequency_penalty, presence_penalty, repetition_penalty — usados os valores configurados no preset (se nenhum estiver configurado, nenhum é enviado ao provedor).
• reasoning_effort — usado o valor configurado no preset.
• A própria escolha de modelo — o preset define seu pool de modelos elegíveis; não é possível apontar para um modelo específico dentro de um preset via model.

O prompt de sistema do preset (se configurado) é adicionado às mensagens da requisição. tools, por outro lado, continua sendo respeitado normalmente mesmo em requisições com preset — não é substituído nem ignorado.

Para o formato de erro e os códigos retornados por esse endpoint, veja Erros.