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

# Guias de Migração

> Mova cargas de trabalho OpenAI, Anthropic, Gemini e de mídia para o TokenLab com pequenas mudanças seguras para produção.

TokenLab é multi-formato: você pode manter clientes compatíveis com OpenAI, chamadas de Messages nativas da Anthropic, chamadas REST nativas da Gemini e endpoints de mídia em suas formas naturais. A migração mais segura não é traduzir cada carga de trabalho em um formato universal. Escolha a rota que possui o comportamento que sua aplicação precisa.

## Mapeamento de Rotas

| Carga de trabalho existente | URL base do TokenLab         | Endpoint principal                      | Nota de migração                                                                                           |
| --------------------------- | ---------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| OpenAI Chat Completions     | `https://api.tokenlab.sh/v1` | `/chat/completions`                     | Menor mudança para chat compatível com OpenAI e chamadas de função                                         |
| OpenAI Responses            | `https://api.tokenlab.sh/v1` | `/responses`                            | Use quando seu aplicativo depende de entrada, ferramentas ou manipulação de saída específicas de Responses |
| Anthropic SDK               | `https://api.tokenlab.sh`    | `/v1/messages`                          | Não acrescente `/v1` à URL base do SDK                                                                     |
| Gemini REST                 | `https://api.tokenlab.sh`    | `/v1beta/models/:model:generateContent` | Mantenha campos nativos da Gemini na rota da Gemini                                                        |
| Geração de mídia            | `https://api.tokenlab.sh/v1` | `/images`, `/videos`, `/music`, `/3d`   | Descubra modelos com `recommended_for` e espere polling assíncrono onde documentado                        |
| Gestão e faturamento        | `https://api.tokenlab.sh/v1` | `/management/...`                       | Use tokens de gestão para uso do lado do servidor e reconciliação de faturamento                           |

## Migração Compatível com OpenAI

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh/v1",
)

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

Mantenha seu código existente de retry, timeout e streaming, mas valide os IDs dos modelos com `GET /v1/models` antes do tráfego de produção. Para geração de imagens, envie `model` explicitamente e leia o guia de imagens porque os modelos de imagem diferem mais do que os modelos de chat.

## Migração da Anthropic

```python theme={null}
from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh",
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain TokenLab in one sentence."}],
)
```

Use `/v1/messages` para uso de ferramentas nativas do Claude, fluxos de pensamento e semântica de mensagens da Anthropic. Não traduza campos exclusivos da Anthropic através de Chat Completions a menos que você queira intencionalmente uma mudança de comportamento compatível com OpenAI.

## Migração da Gemini

```bash theme={null}
curl "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer sk-your-tokenlab-key" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Hello"}]}]}'
```

Mantenha ferramentas integradas da Gemini, referências da API de Arquivo, conteúdos em cache, declarações de função e partes de conteúdo nativas em `/v1beta` quando seu aplicativo depender do comportamento nativo da Gemini.

## Migração de Mídia

1. Consulte `GET /v1/models?recommended_for=image|video|music|3d`.
2. Leia `tokenlab.public_contract_summary` nas respostas da lista e o `tokenlab.public_contract` completo onde disponível.
3. Envie um `model` explícito, especialmente para endpoints de imagem.
4. Armazene `task_id`, `poll_url`, endpoint, modelo e seu próprio ID de trabalho para trabalhos assíncronos.
5. Reconcile custos através de registros de uso e `billing_transaction_id`, não IDs de tarefa do provedor.

Cargas de trabalho de mídia precisam de seu próprio plano de lançamento porque latência, retries e ativos finais se comportam de maneira diferente das conclusões de chat.

## Plano de Lançamento em Produção

| Fase                    | Objetivo                                                                                                              | Verificações                                                                    |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 1. Inventário           | Listar endpoints, modelos, campos de solicitação, comportamento de streaming/assíncrono e proprietário de faturamento | Nenhum campo oculto exclusivo do provedor é assumido como público               |
| 2. Piloto de rota única | Mover um endpoint e uma família de modelos                                                                            | Forma da resposta, custo e logs correspondem às expectativas                    |
| 3. Sombra ou amostra    | Comparar saídas selecionadas com o provedor anterior                                                                  | Qualidade e latência visíveis para o usuário são aceitáveis                     |
| 4. Lançamento gradual   | Aumentar o tráfego por chave, organização ou flag de recurso                                                          | Monitorar `4xx`, `5xx`, latência, equilíbrio e trabalhos assíncronos duplicados |
| 5. Limpeza              | Remover o caminho do provedor antigo somente após uso estável                                                         | O caminho de reversão e o playbook de suporte estão documentados                |

## Armadilhas de Migração

* Não coloque cada modelo atrás de um único caminho de OpenAI Chat Completions se seu aplicativo precisar de comportamento nativo da Anthropic, Gemini ou Responses.
* Não assuma os padrões antigos de imagem. Envie `model` explicitamente.
* Não tente novamente solicitações de criação assíncronas sem verificar se uma tarefa já foi criada.
* Não exponha metadados de roteamento do provedor em seus logs ou UI.
* Não compare faturamento com IDs de tarefa do provedor. Use registros de uso do TokenLab.

## Referência da API

| Tópico                          | Referência                                                        |
| ------------------------------- | ----------------------------------------------------------------- |
| API Multi-Formato               | [API Multi-Formato](/pt/guides/api-formats)                       |
| SDK OpenAI                      | [SDK OpenAI](/pt/integrations/openai-sdk)                         |
| SDK Anthropic                   | [SDK Anthropic](/pt/integrations/anthropic-sdk)                   |
| Nativo da Gemini                | [API Nativa da Gemini](/pt/api-reference/gemini/generate-content) |
| Geração de Imagem               | [Geração de Imagem](/pt/guides/image-generation)                  |
| Trabalhos Assíncronos & Polling | [Trabalhos Assíncronos & Polling](/pt/guides/async-jobs-polling)  |