> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrar da OpenAI, Anthropic, OpenRouter e LiteLLM

> Transfira o tráfego de LLM existente para o AI Gateway do Toqan Router a partir do SDK da OpenAI, do SDK da Anthropic, do OpenRouter ou do LiteLLM alterando a URL base, a chave de API e o nome do modelo.

O **AI Gateway** usa o formato da API da OpenAI e expõe um endpoint compatível com a Anthropic em `/v3/anthropic` para códigos existentes do **SDK da Anthropic**. Migrar uma aplicação existente significa alterar três valores: a URL base, a chave de API e o nome do modelo. Os corpos de requisição, os corpos de resposta e o streaming permanecem iguais. A chamada de ferramentas não muda para a maioria dos modelos, com uma exceção indicada abaixo.

## O que muda

| Item | Alterar para |
| - | - |
| URL base | `https://router.toqan.ai/eu/v3/router`, ou `https://router.toqan.ai/eu/v3/anthropic` para a Anthropic Messages API. A mesma para todas as organizações, workspaces e projetos |
| Header de autorização | `Bearer $TOQAN_API_KEY`, ou `x-api-key: $TOQAN_API_KEY`, que o **SDK da Anthropic** envia por padrão. Os dois headers são aceitos |
| Nome do modelo | `provider/model`, por exemplo `openai/gpt-5.6-sol`. Sempre inclua o prefixo: alguns modelos são servidos por mais de um provedor, e o prefixo escolhe entre eles |

A URL base não varia por região nem por workspace. Os dados armazenados na plataforma do **Toqan Router** residem na União Europeia, enquanto a região a partir da qual um modelo é servido depende do modelo e pode ser filtrada na página **Models**. Consulte Sovereign AI.

Um modelo privado carrega seu workspace no nome do modelo, como `<workspace>@<provider>/<model>`, e não na URL. Consulte [Modelos privados](/docs/pt-BR/ai-gateway/private-models.md).

## O que funciona imediatamente

Assim que esses três valores estiverem definidos, os itens a seguir não exigem mais código:

* **Custo por chamada**: cada requisição registra o custo de entrada, de saída e o custo total.
* **Traces**: cada requisição é registrada com sua latência, as contagens de tokens e o modelo que respondeu.
* **Acesso a modelos**: todos os modelos habilitados na [página Models](/docs/pt-BR/ai-gateway/using-the-router.md) podem ser acessados pelo mesmo cliente, independentemente do provedor que os serve. Explore o catálogo em [Supported Models](/docs/pt-BR/ai-gateway/supported-models.md).
* **Routing Rules**: roteie ou restrinja o tráfego pela interface do **AI Gateway**, sem mexer na aplicação. Consulte [Routing Rules](/docs/pt-BR/ai-gateway/configuration/routing-rules.md).

**Fallbacks**, **Retries**, **Cache** e **Guardrails** são campos opcionais no corpo da requisição, abordados em [O que o Toqan Router adiciona](#what-toqan-router-adds).

## O que não é transferido

Três áreas não são transferidas.

| Área | Detalhe |
| - | - |
| Assistants API e fine-tuning | Não disponíveis. `/assistants` e `/fine_tuning/jobs` retornam `404`. Aplicações construídas sobre esses endpoints não podem ser migradas como estão. Consulte [API compatível com OpenAI](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md) para a lista de endpoints suportados. |
| Chamada de ferramentas com modelos de raciocínio da OpenAI | Enviar `tools` para `/chat/completions` com um modelo de raciocínio como `openai/gpt-5.6-sol` retorna `400`. Use `/responses` em vez disso. Definir `reasoning_effort` como `none` também desbloqueia `/chat/completions`, ao custo do raciocínio que o modelo faria normalmente. Outros modelos, incluindo `openai/gpt-5.4-mini` e `anthropic/claude-sonnet-5`, aceitam `tools` em `/chat/completions` normalmente. |
| Download dos resultados de batch | As chamadas de criação, consulta, listagem e cancelamento de batches funcionam com `/v3/router`. Baixe a saída de `GET /v3/router/batches/{batch_id}/results` em vez do endpoint de arquivos da OpenAI. Consulte [Batches](/docs/pt-BR/ai-gateway/features/batches.md). |

## Antes de começar

Conclua primeiro o [Quick Start](/docs/pt-BR/ai-gateway/get-started/introduction.md). Uma migração precisa de uma chave de API, e todos os modelos que a aplicação chama precisam estar habilitados na [página Models](/docs/pt-BR/ai-gateway/using-the-router.md), e não apenas o usado na primeira requisição.

O acesso a esses modelos vem de **Créditos** ou de [**BYOK**](/docs/pt-BR/ai-gateway/providers-overview.md).

Exporte a chave antes de começar. As etapas abaixo a leem, assim como o agente de programação quando verifica os nomes dos modelos em relação ao catálogo.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export TOQAN_API_KEY="your-api-key"
```

## Migrar com um agente de programação

Cole o prompt abaixo em um agente de programação como **Claude Code**, **Cursor** ou **Codex**. O agente encontra as chamadas de LLM no repositório e as reescreve.

O prompt faz o seguinte:

1. Aponta todos os clientes de LLM para `https://router.toqan.ai/eu/v3/router`, ou para `https://router.toqan.ai/eu/v3/anthropic` no caso de um cliente do **SDK da Anthropic**.
2. Substitui a variável da chave de API antiga por `TOQAN_API_KEY`, no código e nos arquivos de ambiente, mantendo `ANTHROPIC_API_KEY` e `ANTHROPIC_BASE_URL` onde o **SDK da Anthropic** os lê pelo nome.
3. Reescreve os nomes dos modelos no formato `provider/model`.
4. Converte as configurações de roteamento do gateway anterior em vez de excluí-las.
5. Verifica cada nome de modelo em relação ao catálogo e deixa um ponto de chamada intocado em vez de substituir um modelo ou migrá-lo pela metade.
6. Não altera o tratamento de requisições e respostas.

Comece a partir de uma árvore de trabalho do git limpa, para que todas as alterações fiquem visíveis em `git diff` e possam ser revertidas com `git checkout .`. Revise o diff antes de executar a aplicação.

Prefere migrar manualmente? Vá para [Migrar do SDK da OpenAI](#migrate-from-the-openai-sdk) ou [Migrar do SDK da Anthropic](#migrate-from-the-anthropic-sdk).

```text Migration prompt theme={"theme":{"light":"github-light","dark":"github-dark"}}
Migrate this project to the Toqan Router AI Gateway. Make the smallest change that works. Do not restructure the application.

Step 1. Find every place the project calls an LLM. Check source files, configuration files, environment files, and container definitions.

Step 2. Identify the current setup, then apply the matching rule:
- OpenAI SDK with no custom base URL: add the base URL below and change the API key variable.
- Anthropic SDK (an Anthropic client, or ANTHROPIC_BASE_URL set): point the client at the Anthropic-compatible base URL below and keep its request format. Where the key is a constructor argument, change it to TOQAN_API_KEY. Where the client reads ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL from the environment, keep both variable names and change only their values to the Toqan Router key and the Anthropic-compatible base URL, because the SDK resolves those names itself.
- OpenRouter (base URL contains openrouter.ai): replace the base URL and the API key variable, then convert the OpenRouter settings using Step 3.
- LiteLLM proxy (base URL points at a self-hosted proxy): replace the base URL and the API key variable. Replace each model alias with the full provider/model name, read from litellm_params.model in the LiteLLM config file.
- LiteLLM Python library used directly: keep the library and set api_base to the base URL below, and prefix each model with openai/, giving openai/<provider>/<model>. LiteLLM strips that openai/ prefix before forwarding, so the gateway receives <provider>/<model>. Do not replace the library.

Step 3. Convert OpenRouter settings. Do not delete them silently, because they carry routing behavior:
- models array with route: "fallback" becomes fallbacks: [{"model": "..."}]. The first entry of the models array repeats the top-level model field, so leave it out and list only the entries after it. Including it makes the request fall back to the model that just failed.
- provider preferences: remove every sub-option from the request and report each one by name. There is no drop-in request-body equivalent. Choosing between models per request maps to the load_balancer field, and organization-wide routing maps to Routing Rules in the Toqan Router interface. Do not write either one, because both need a human decision.
- plugins: remove the field and report every entry by name. Toqan Router uses the same field name with different accepted id values, and an unrecognized id makes the whole request fail with a 400, so keeping the array breaks the call site. Do not write a replacement, because the equivalent needs a human decision.
- debug: remove.
- Headers HTTP-Referer, X-Title, X-OpenRouter-Title, X-OpenRouter-Categories: remove and report each one. Do not write a replacement. The application name maps to the name field, which a human can add later.

Step 4. Apply these values:
- Base URL: https://router.toqan.ai/eu/v3/router, or https://router.toqan.ai/eu/v3/anthropic at an Anthropic SDK call site. Never point an Anthropic client at the router.
- Auth: Authorization: Bearer $TOQAN_API_KEY. At an Anthropic SDK call site the client sends x-api-key by default, which the gateway also accepts; leave that header as it is.
- Environment variable: TOQAN_API_KEY. Do not add fallback variables. Rename the variable in code, in committed templates such as .env.example, and in container definitions. At an Anthropic SDK call site that reads ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL from the environment, keep those names and change only their values. In templates, leave the value empty. Remove an old provider or gateway variable only when nothing in this repository still reads it, and list every variable removed. Never read, print, or copy a secret value. If a file holds real secrets, report its path instead of editing it.
- Model format: provider/model, for example openai/gpt-5.6-sol or anthropic/claude-sonnet-5.

Step 5. Model names. Never substitute a different model version, because cost and behavior differ. A newer version is not an equivalent, and a similar name carrying a different identifier is not the same model. Check every name against the catalog:

curl https://router.toqan.ai/eu/v3/router/models -H "Authorization: Bearer $TOQAN_API_KEY"

Match names exactly. A punctuation difference or an added date suffix makes it a different model. At a LiteLLM Python library call site, look up only the part after the openai/ prefix, because that is the name the gateway receives.

Take the provider segment from the code where it is stated: a client configured against one specific provider, or a config entry that names it. Where the code does not state it, a provider may be proposed, but only keep the result if that exact provider/model appears in the catalog, and report the inference. Never keep a provider that the catalog does not confirm.

Flag a model instead of changing it when the name is absent from the catalog, when the catalog cannot be reached, or when no candidate provider/model can be confirmed against the catalog.

Step 6. Leave every call site that has a flagged model completely unchanged, including its base URL, its API key variable, and any environment variable only that call site still uses. Migrating the rest of such a call site produces a request that fails at runtime. Report each one as blocked on a decision. This overrides Step 3: report the settings on a blocked call site instead of converting them. Where one shared client object serves both migrated and blocked calls, leave that client as it is and add a separate client for the migrated calls, rather than repointing the one the blocked call still depends on.

Step 7. Remove configuration that existed only to run the previous gateway, such as a LiteLLM config file and its proxy service definition. Keep anything a call site blocked in Step 6 still needs. List every file removed.

Step 8. Do not change message content, response handling, streaming logic, or tool-calling logic. The API format is identical. The only body changes permitted are the field conversions in Step 3.

Step 9. Report three lists:
- model names changed, as old name and new name
- model names flagged for a human decision, and the call sites left unmigrated because of them
- settings that moved to the Toqan Router interface instead of code

Show the full diff. Do not commit.
```

> [!WARNING]
>
> Não há garantia de que os nomes dos modelos sejam iguais entre gateways. Verifique cada nome reportado pelo agente em [Supported Models](/docs/pt-BR/ai-gateway/supported-models.md) antes de executar a aplicação em produção. Um `404` significa que o nome está errado ou que o modelo não está habilitado na [página Models](/docs/pt-BR/ai-gateway/using-the-router.md). `fallbacks` não cobre esse caso, porque o modelo é resolvido antes da execução do roteamento.

## Migrar do SDK da OpenAI

Altere a URL base e a chave de API. Adicione o prefixo do provedor ao nome do modelo.

Tanto `/chat/completions` quanto `/responses` estão disponíveis, então mantenha o que a aplicação já usa.

**Antes**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),
)

response = client.responses.create(
    model="gpt-5.6-sol",
    input="Hello!",
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const response = await client.responses.create({
  model: "gpt-5.6-sol",
  input: "Hello!",
});
```

**Depois**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.environ.get("TOQAN_API_KEY"),
)

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Hello!",
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

const response = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "Hello!",
});
```

Os modelos de todos os outros provedores agora funcionam pelo mesmo cliente. Consulte [Supported Models](/docs/pt-BR/ai-gateway/supported-models.md).

## Migrar do SDK da Anthropic

Altere a URL base e a chave de API. Adicione o prefixo do provedor ao nome do modelo. O **SDK da Anthropic** acrescenta `/v1/messages` à URL base, então nenhum caminho muda, e as requisições ao Claude mantêm streaming, uso de ferramentas e entrada multimodal sem alterações. Consulte [Anthropic Messages API](/docs/pt-BR/ai-gateway/features/anthropic-messages-api.md).

**Antes**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import anthropic
import os

client = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});
```

**Depois**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import anthropic
import os

client = anthropic.Anthropic(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/anthropic",
)

message = client.messages.create(
    model="anthropic/claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/anthropic",
});

const message = await client.messages.create({
  model: "anthropic/claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello!" }],
});
```

O SDK também lê `ANTHROPIC_API_KEY` e `ANTHROPIC_BASE_URL` do ambiente, caso a aplicação os defina lá em vez de no cliente: defina `ANTHROPIC_API_KEY` com a chave do **Toqan Router** e `ANTHROPIC_BASE_URL` com `https://router.toqan.ai/eu/v3/anthropic`. Modelos que não são Claude podem ser acessados pelo mesmo endpoint alterando o prefixo do modelo.

## Migrar do OpenRouter

O **OpenRouter** e o **AI Gateway** usam o mesmo formato de nomes `provider/model`, então a maioria dos nomes de modelos continua igual. Os catálogos são diferentes, portanto confirme cada nome em `GET /models` ou na página **Models** antes de fazer a troca.

**Antes**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ.get("OPENROUTER_API_KEY"),
)

response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [{ role: "user", content: "Hello!" }],
});
```

**Depois**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.environ.get("TOQAN_API_KEY"),
)

response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [{ role: "user", content: "Hello!" }],
});
```

### Transferir as configurações do OpenRouter

A maioria dos campos antigos do **OpenRouter** é ignorada em vez de rejeitada, então uma migração parcial não falha. O roteamento que eles configuravam deixa de ser aplicado. Transfira cada um de forma deliberada.

`plugins` é a exceção. Os dois gateways usam esse nome de campo, e o **AI Gateway** o lê. Um array `plugins` remanescente do **OpenRouter** faz a chamada inteira falhar com um `Invalid request body` genérico, que não indica o campo.

| Configuração do OpenRouter | Equivalente no **Toqan Router** |
| - | - |
| Array `models` com `route: "fallback"` | [`fallbacks`](/docs/pt-BR/ai-gateway/features/retries#fallbacks), listando as entradas após a primeira. A primeira repete `model` |
| `provider.order`, `provider.only`, `provider.ignore` | [`load_balancer`](/docs/pt-BR/ai-gateway/features/load-balancing) para escolher entre modelos a cada requisição, ou [Routing Rules](/docs/pt-BR/ai-gateway/configuration/routing-rules.md) para restringir o roteamento de toda a organização |
| `provider.allow_fallbacks` | [`fallbacks`](/docs/pt-BR/ai-gateway/features/retries#fallbacks), que é explícito em vez de automático |
| `provider.data_collection`, `provider.zdr` | A retenção zero de dados é uma propriedade do modelo. Filtre por ela na página **Models**. Consulte Sovereign AI |
| `provider.sort` | [`load_balancer`](/docs/pt-BR/ai-gateway/features/load-balancing) com seleção baseada em latência |
| Array `plugins` | `plugins`: mesmo nome de campo, valores de `id` aceitos diferentes. Remova o array do **OpenRouter** em vez de mantê-lo, porque um `id` não reconhecido retorna `400` |
| Headers `HTTP-Referer`, `X-Title`, `X-OpenRouter-Title`, `X-OpenRouter-Categories` | [`name`](/docs/pt-BR/ai-gateway/app-tracking) para o nome da aplicação, [`metadata`](/docs/pt-BR/ai-gateway/request-metadata) para rótulos filtráveis |

As demais subopções de `provider` não têm equivalente por requisição: `require_parameters`, `quantizations`, `enforce_distillable_text`, `preferred_min_throughput`, `preferred_max_latency` e `max_price`. Aplicações que dependem de qualquer uma delas precisam ter o roteamento definido antes da requisição, selecionando os modelos explicitamente ou por meio de [Routing Rules](/docs/pt-BR/ai-gateway/configuration/routing-rules.md).

## Migrar do LiteLLM

O **LiteLLM Proxy** é um servidor executado na própria infraestrutura da organização. As aplicações o chamam em vez de chamar os provedores diretamente, e ele encaminha cada requisição ao provedor real. Ele expõe um endpoint compatível com OpenAI, na porta 4000 por padrão.

Há duas formas de deixá-lo. Escolha uma antes de fazer qualquer alteração.

| Opção | O que acontece | Contrapartida |
| - | - | - |
| **Desativar o proxy** (abordado abaixo) | A aplicação chama o **AI Gateway** diretamente e o servidor **LiteLLM** é desligado | Todos os nomes de modelos na aplicação precisam ser reescritos |
| **Manter o proxy por trás do Toqan Router** | A instância do **LiteLLM** é conectada como provedor e seus modelos são importados. Cada nome mantém seu apelido, com o prefixo `<workspace>@litellm/<nickname>`, então nenhum modelo real precisa ser consultado | O servidor **LiteLLM** permanece na stack, e todos os nomes de modelos ainda precisam receber o prefixo. Consulte [Provedor de modelos personalizados LiteLLM](/docs/pt-BR/ai-studio/integrations/providers/litellm.md) |

O restante desta seção aborda a primeira opção.

### Encontrar o nome real do modelo

O **LiteLLM Proxy** não usa os nomes de modelos dos provedores. Ele usa apelidos definidos em seu `config.yaml`. Cada entrada associa o apelido que a aplicação chama ao modelo real por trás dele:

```yaml config.yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
model_list:
  - model_name: fast-model            # the nickname the application sends
    litellm_params:
      model: openai/gpt-5.6-sol       # the real model it forwards to
```

A aplicação abaixo envia `fast-model`. O **AI Gateway** não tem esse nome, então substitua-o pelo modelo real, `openai/gpt-5.6-sol`. Abra o `config.yaml` e leia o valor de `litellm_params.model` de cada apelido que a aplicação usa.

> [!WARNING]
>
> Um apelido pode ser idêntico ao nome de um modelo real. `model_name: gpt-5.6-sol` pode apontar para `litellm_params.model: azure/gpt-5.6-sol-global`, que é um modelo diferente em um provedor diferente. Leia `litellm_params.model` em todas as entradas, incluindo as que já parecem corretas.

### Alterar o cliente

**Antes**, apontando para o proxy e chamando-o pelo apelido:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url="http://localhost:4000",
    api_key=os.environ.get("LITELLM_API_KEY"),
)

response = client.chat.completions.create(
    model="fast-model",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:4000",
  apiKey: process.env.LITELLM_API_KEY,
});

const response = await client.chat.completions.create({
  model: "fast-model",
  messages: [{ role: "user", content: "Hello!" }],
});
```

**Depois**, apontando para o **AI Gateway** e chamando o modelo real:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.environ.get("TOQAN_API_KEY"),
)

response = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  messages: [{ role: "user", content: "Hello!" }],
});
```

O comportamento de roteamento definido no `config.yaml`, como fallbacks e novas tentativas, passa para o corpo da requisição. Consulte [O que o Toqan Router adiciona](#what-toqan-router-adds).

Para manter o **LiteLLM** como chamador e enviar seus traces para o **Toqan Router**, consulte Observabilidade do LiteLLM.

## Verificar a migração

**1. Envie uma requisição**

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Confirm the migration works."
  }'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.environ.get("TOQAN_API_KEY"),
)

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Confirm the migration works.",
)

print(response.output_text)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

const response = await client.responses.create({
  model: "openai/gpt-5.6-sol",
  input: "Confirm the migration works.",
});

console.log(response.output_text);
```

Uma resposta `200` confirma que a URL base, a chave de API e o nome do modelo estão corretos.

Para uma aplicação que usa chat completions, substitua `/responses` por `/chat/completions` e envie `messages` em vez de `input`.

**2. Verifique o trace**

Abra **Traces** no **AI Gateway** e abra a requisição mais recente. Confirme os quatro itens:

| Verificação | Esperado | Se não corresponder |
| - | - | - |
| Custo total | Maior que zero | O modelo não tem preço associado ou a conexão com o provedor está ausente. Verifique o modelo na [página Models](/docs/pt-BR/ai-gateway/using-the-router.md) |
| Modelo que respondeu | O mesmo modelo solicitado, exibido sem o prefixo `provider/`. Solicitar `openai/gpt-5.6-sol` reporta `gpt-5.6-sol` | Um modelo diferente significa que um fallback ou uma [Routing Rule](/docs/pt-BR/ai-gateway/configuration/routing-rules.md) redirecionou a chamada |
| Tokens de entrada e de saída | Ambos maiores que zero | A requisição ou a resposta estava vazia |
| Status | Concluído, sem erro | Inspecione o erro do provedor no trace |

Se nenhuma requisição aparecer, a aplicação ainda está chamando o endpoint antigo. Pesquise no repositório a URL base anterior e a variável de chave anterior.

**3. Transfira o tráfego restante**

Repita para cada serviço que chama um LLM. Filtre os **Traces** por modelo para confirmar que todos os modelos que a aplicação usa agora aparecem e para encontrar o tráfego que ainda não foi transferido.

## O que o Toqan Router adiciona

Com o tráfego fluindo, estes campos opcionais vão no mesmo corpo da requisição.

| Campo | O que faz | Referência |
| - | - | - |
| `fallbacks` | Tenta outro modelo quando o primeiro falha | [Fallbacks](/docs/pt-BR/ai-gateway/features/retries.md#fallbacks) |
| `retry` | Repete uma requisição que falhou, com quantidade e códigos de erro configuráveis | [Retries](/docs/pt-BR/ai-gateway/features/retries.md) |
| `timeout` | Para de aguardar um provedor após um número definido de milissegundos | [Timeouts](/docs/pt-BR/ai-gateway/features/timeouts.md) |
| `load_balancer` | Divide o tráfego entre vários modelos por peso ou latência | [Balanceamento de carga](/docs/pt-BR/ai-gateway/features/load-balancing.md) |
| `cache` | Retorna uma resposta armazenada para uma requisição idêntica repetida | [Cache](/docs/pt-BR/ai-gateway/features/cache.md) |
| `guardrails` | Verifica a entrada ou a saída e bloqueia a requisição quando uma verificação falha | [Guardrails](/docs/pt-BR/ai-gateway/configuration/guardrails.md) |
| `plugins` | Remove dados pessoais antes que o provedor os veja ou corrige JSON malformado | Plugins |
| `security` | Mascara os dados de requisição e resposta nos traces armazenados | [Segurança](/docs/pt-BR/ai-gateway/features/security.md) |
| `name` | Nomeia a aplicação chamadora no trace | [App Tracking](/docs/pt-BR/ai-gateway/app-tracking.md) |
| `thread` | Agrupa os turnos de uma conversa | [Threads](/docs/pt-BR/ai-gateway/thread-management.md) |
| `identity` | Atribui uma requisição, e seu custo, a um usuário final | [Identities](/docs/pt-BR/ai-studio/observability/identities.md) |

Definidos na interface do **Toqan Router**, e não no corpo da requisição: [Orçamentos](/docs/pt-BR/ai-gateway/budgets.md) para limites de gasto e alertas, [Modelos privados](/docs/pt-BR/ai-gateway/private-models.md) para modelos auto-hospedados ou ajustados e Sovereign AI para residência de dados e provedores com retenção zero.

Adicionando um fallback e um cache a uma chamada existente:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "messages": [{ "role": "user", "content": "Hello!" }],
    "fallbacks": [{ "model": "anthropic/claude-sonnet-5" }],
    "cache": { "type": "exact_match", "ttl": 3600 }
  }'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.environ.get("TOQAN_API_KEY"),
)

response = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={
        "fallbacks": [{"model": "anthropic/claude-sonnet-5"}],
        "cache": {"type": "exact_match", "ttl": 3600},
    },
)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

const toqanFields = {
  fallbacks: [{ model: "anthropic/claude-sonnet-5" }],
  cache: { type: "exact_match", ttl: 3600 },
};

const response = await client.chat.completions.create({
  model: "openai/gpt-5.6-sol",
  messages: [{ role: "user", content: "Hello!" }],
  ...toqanFields,
});
```

## Próximos passos

> [card] [Fallbacks e Retries](/docs/pt-BR/ai-gateway/features/retries.md)
>
> Mantenha as requisições fluindo quando um provedor falhar.

> [card] [Supported Models](/docs/pt-BR/ai-gateway/supported-models.md)
>
> Explore o catálogo de modelos e as funcionalidades dos provedores.

> [card] [API compatível com OpenAI](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md)
>
> Consulte a lista completa de endpoints compatíveis.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.