---
title: "Migrar para API compatível com a OpenAI: checklist | BroadRouter"
description: "Trocar o base_url é a parte fácil. O que quebra são IDs de modelo, tokens de raciocínio, usage no streaming, erros, rate limits e chaves. Checklist com código."
url: https://broadrouter.com/pt/blog/openai-compatible-api-migration-checklist/
lang: pt-BR
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/blog/openai-compatible-api-migration-checklist/) (atualizado em 2026-11-16).

# Migrar para uma API compatível com a OpenAI: checklist de migração

Pela equipe da BroadNet Inference · 5 min de leitura · Publicado em 2026-11-14 · Atualizado em 2026-11-16

Para migrar para uma API compatível com a OpenAI, troque três configurações (base\_url, api\_key e model) e depois confira o que muda: IDs de modelo, como os tokens de raciocínio contam no max\_tokens, como o streaming informa o usage, quais erros repetir, rate limits e segurança das chaves. Na BroadNet Inference, a base URL é https://inference.broadnet.ai/v1.

## Pontos principais

-   Mudam três configurações: `base_url`, `api_key` e `model`.
-   Antes de trocar, faça o inventário de cada endpoint e campo que o seu app usa, depois teste um por um.
-   Modelos de raciocínio contam o raciocínio no `max_tokens`; limites baixos devolvem respostas vazias.
-   Peça o usage nos streams com `stream_options`, senão o controle de custos fica às cegas.
-   Antes de mover o tráfego de produção, defina para cada código de erro se é para repetir ou corrigir.
-   Rode o provedor antigo e o novo lado a lado com tráfego real por um dia antes da virada.

**Nesta página**

1.  0\. O que o seu app usa hoje?
2.  1\. Quais três configurações mudam?
3.  2\. Quais são os novos IDs de modelo?
4.  3\. Por que as respostas voltam vazias depois da troca?
5.  4\. O streaming ainda informa o usage?
6.  5\. Quais erros vale repetir?
7.  6\. Quais são os novos rate limits?
8.  7\. Os seus prompts ainda cabem?
9.  8\. E as chaves e a retenção de dados?
10.  9\. Como fazer a virada com segurança?
11.  Quais são os erros de migração mais comuns?
12.  Onde a BroadNet Inference se encaixa

Hoje a maioria dos provedores de LLM fala o [formato da API da OpenAI](https://broadrouter.com/pt/glossary/openai-compatible-api/). Isso faz a troca parecer uma mudança de uma linha, e para obter a primeira resposta é mesmo. Para rodar tráfego de produção, siga esta lista. Cada item vem de um jeito real como migrações quebram.

## 0\. O que o seu app usa hoje?

Antes de mudar qualquer coisa, anote do que o seu app depende. Procure no código todas as chamadas ao SDK e liste. Se você chama a API Whisper da OpenAI, saiba que a OpenAI lista o `whisper-1` com desativação em 26 de fevereiro de 2027; [alternativas à API do Whisper](https://broadrouter.com/pt/blog/whisper-api-alternative/) cobre a parte de áudio.

| Recurso | Onde procurar | Teste depois da troca |
| --- | --- | --- |
| Chat completions | Cada `chat.completions.create` | Mesmos prompts, compare as respostas |
| Streaming | `stream=True` | Os chunks chegam, termina com `[DONE]`, usage presente |
| Tool calling | `tools=` | As chamadas de ferramenta são parseadas e executadas |
| Saída estruturada | `response_format=` | O JSON valida contra o seu schema |
| Imagens | Partes de imagem nas mensagens | O modelo aceita |
| Transcrição de áudio | `audio.transcriptions` | Texto e idioma corretos |
| Embeddings, arquivos, batches | Outros endpoints | Confira se o provedor oferece |

A última linha importa. “Compatível com a OpenAI” normalmente cobre primeiro as chat completions. O catálogo da BroadNet Inference lista modelos de chat em `/v1/chat/completions` e modelos de fala para texto em `/v1/audio/transcriptions`; se você usa outros endpoints, mantenha-os no provedor atual ou encontre um substituto.

## 1\. Quais três configurações mudam?

```python
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)
```

O nome da configuração de [base URL](https://broadrouter.com/pt/glossary/base-url/) muda de biblioteca para biblioteca: `base_url` no SDK Python e no ChatOpenAI do LangChain, `baseURL` no SDK Node.js. Segundo o [README](https://github.com/openai/openai-python), o SDK Python também lê a variável de ambiente `OPENAI_BASE_URL`. Verifique se não sobrou um valor antigo no seu ambiente, ou as requisições podem ir para o provedor antigo sem nenhum erro.

Guarde as [chaves de API](https://broadrouter.com/pt/glossary/api-key/) em variáveis de ambiente ou num gerenciador de segredos, nunca no código. Configuração de cada SDK: [Python](https://broadrouter.com/pt/guides/openai-python-sdk/), [Node.js](https://broadrouter.com/pt/guides/openai-node-sdk/), [LangChain](https://broadrouter.com/pt/guides/langchain-openai-base-url/). Para montar e testar uma primeira requisição à mão, use o [construtor de requisições de API](https://broadrouter.com/tools/api-request-builder/). Para aplicar as mudanças de base URL, chave e modelo ao código que você já tem, cole-o no [assistente de migração da OpenAI para a BroadNet](https://broadrouter.com/tools/openai-to-broadnet-migration/), que também lista o que conferir.

## 2\. Quais são os novos IDs de modelo?

Cada provedor dá nome aos modelos do seu jeito. Na BroadNet Inference:

| Modelo | ID |
| --- | --- |
| DeepSeek V4.1 Flash | `broadnet/deepseek-v4.1-flash` |
| GLM 5.3 | `broadnet/glm-5.3` |
| Qwen3.8 27B | `broadnet/qwen3.8-27b` |
| Gemma 4 VL 26B | `broadnet/gemma-4-26b-a4b` |

Coloque o ID do modelo na configuração, não no código, para que uma troca futura seja um deploy e não uma reescrita. Os limites e preços de cada modelo estão na página dele: [DeepSeek V4.1 Flash](https://broadrouter.com/pt/models/deepseek-v4.1-flash/), [GLM 5.3](https://broadrouter.com/pt/models/glm-5.3/), [Qwen3.8 27B](https://broadrouter.com/pt/models/qwen3.8-27b/) e [Gemma 4 VL 26B](https://broadrouter.com/pt/models/gemma-4-vl-26b/).

## 3\. Por que as respostas voltam vazias depois da troca?

Essa é a surpresa mais comum. DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam antes de responder, e **os [tokens de raciocínio](https://broadrouter.com/pt/glossary/reasoning-tokens/) contam no [`max_tokens`](https://broadrouter.com/pt/glossary/max-tokens/)**. Um limite de 256 que funcionava num modelo sem raciocínio pode ser gasto inteiro pensando, e a resposta volta vazia. Deixe 1.000 tokens ou mais, ou defina `reasoning_effort` como `low` para tarefas simples. [Explicação completa](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/).

## 4\. O streaming ainda informa o usage?

Os [streams](https://broadrouter.com/pt/glossary/streaming/) usam Server-Sent Events e terminam com `data: [DONE]`. O uso de tokens só chega no último chunk se você pedir:

```python
stream = client.chat.completions.create(
    model="broadnet/deepseek-v4.1-flash", messages=messages,
    stream=True, stream_options={"include_usage": True},
)
```

Sem isso, o seu painel de custos marca zero. Se um stream terminar antes do `[DONE]`, trate-o como incompleto. [Guia de streaming](https://broadrouter.com/pt/guides/streaming-chat-completions/).

## 5\. Quais erros vale repetir?

| Status | Significado | O que fazer |
| --- | --- | --- |
| 401 | Chave errada ou revogada, ou franquia de pagamento por uso esgotada | Corrija, não repita |
| 402 | Saldo ou orçamento | Faça uma recarga, não repita |
| 403 | Recusada pela política de modelo, rota ou IP | Corrija a divergência |
| 413 | Requisição grande demais | Reduza, não repita |
| 429 | Limite de taxa, simultaneidade ou gasto | Faça backoff e repita |
| 5xx | Lado do servidor | Repita com backoff limitado |

O SDK Python oficial já repete alguns erros: o README diz que erros de conexão, 408, 409, 429 e respostas 5xx são repetidos duas vezes por padrão, com um backoff exponencial curto. Defina `max_retries` explicitamente, para que o comportamento seja uma decisão sua e não um padrão. Registre em log o ID da requisição de cada resposta para que o suporte consiga rastrear um problema. [Todos os códigos](https://broadrouter.com/pt/guides/errors-and-retries/).

## 6\. Quais são os novos rate limits?

Conheça os novos limites antes de o tráfego chegar. Uma chave BroadNet de pagamento por uso permite 30 requisições por minuto e 4 em andamento. Os planos ilimitados rodam uma requisição por vez por sessão. Dimensione o seu pool de workers de acordo, ou você vai ver 429 já no primeiro dia; a [calculadora de rate limit](https://broadrouter.com/tools/llm-rate-limit-calculator/) faz o dimensionamento. Veja [dimensionamento para agentes em paralelo](https://broadrouter.com/pt/blog/run-parallel-coding-agents-flat-rate/).

## 7\. Os seus prompts ainda cabem?

Confira as janelas de contexto: 1.048.576 tokens no DeepSeek V4.1 Flash e no GLM 5.3, 262.144 no Qwen3.8 27B, 32.768 no Gemma 4 VL 26B. Um prompt que cabia no modelo antigo pode não caber numa janela menor; confira com a [calculadora de janela de contexto](https://broadrouter.com/tools/context-window-calculator/). Deixe o conteúdo estável do prompt no início para aproveitar o [preço de entrada em cache](https://broadrouter.com/pt/blog/cached-input-tokens-explained/).

## 8\. E as chaves e a retenção de dados?

Restrinja as chaves de produção aos IPs dos seus servidores com uma [lista de IPs permitidos](https://broadrouter.com/pt/guides/api-keys-ip-allow-lists/). Pergunte ao novo provedor o que ele retém; veja o [checklist de ZDR](https://broadrouter.com/pt/blog/zero-data-retention-llm-api-checklist/).

## 9\. Como fazer a virada com segurança?

1.  Envie uma cópia das requisições reais de um dia para os dois provedores.
2.  Compare as respostas numa amostra, além de latência, erros e custo por requisição.
3.  Mova 10% do tráfego, observe por um dia e depois mova o resto.
4.  Mantenha o provedor antigo configurado como fallback por uma semana.

Se você roda muitos serviços, um proxy como o [LiteLLM](https://broadrouter.com/pt/guides/litellm-proxy-custom-provider/) permite trocar de provedor num só lugar em vez de em cada app.

## Quais são os erros de migração mais comuns?

-   **Falta `/v1` na base URL.** As requisições retornam 404. Use a URL completa.
-   **Nomes de modelo antigos na configuração.** O novo provedor não os conhece.
-   **Campos específicos do provedor esquecidos nas requisições.** Campos que só o provedor antigo entendia podem ser rejeitados ou ignorados. Tire-os dos clients genéricos.
-   **Testar só um prompt.** Percorra o inventário do passo 0, recurso por recurso.
-   **Fazer a virada numa sexta-feira.** Reserve tempo para acompanhar um dia inteiro de tráfego real.

## Onde a BroadNet Inference se encaixa

A BroadNet Inference é um destino plug-and-play para apps que usam chat completions e transcrição de áudio pelos SDKs da OpenAI: troque três configurações e siga a lista acima. O catálogo dela lista apenas modelos de chat e de fala para texto, então, se você depende de outros endpoints, como embeddings ou armazenamento de arquivos, mantenha-os em outro provedor. Contas novas começam com $5 de crédito. Entre os modelos de chat, ele só vale para o Gemma 4 VL 26B (também cobre os dois modelos Transcribe), então um teste em paralelo com DeepSeek, GLM ou Qwen exige uma recarga.

Ferramentas gratuitas sobre o tema (em inglês)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Ferramentas gratuitas (em inglês)](https://broadrouter.com/tools/)

## Termos neste artigo

[Token](https://broadrouter.com/pt/glossary/token/)

Um token é a unidade de texto que um modelo de linguagem lê e escreve: uma palavra, parte de uma palavra, um sinal de pontuação ou uma sequência de bytes gerada pelo tokenizador do modelo. As APIs de LLM contam, limitam e normalmente cobram o uso em tokens.

[Streaming](https://broadrouter.com/pt/glossary/streaming/)

Streaming é uma forma de devolver a resposta de um modelo de linguagem em pequenos pedaços enquanto ela ainda está sendo gerada, em vez de uma resposta única no final. APIs compatíveis com a OpenAI fazem streaming via server-sent events quando a requisição define stream como true.

[Rate limit (limite de taxa)](https://broadrouter.com/pt/glossary/rate-limit/)

Um rate limit é um teto que uma API impõe a quanto um cliente pode usá-la em um intervalo de tempo, como requisições por minuto ou tokens por minuto. As requisições acima do limite são recusadas, normalmente com HTTP 429 Too Many Requests, até que o uso volte a ficar abaixo dele.

[Base URL (URL base)](https://broadrouter.com/pt/glossary/base-url/)

A base URL é o endereço raiz fixo de uma API, como https://api.example.com/v1, que um cliente coloca antes de cada caminho de endpoint, como /chat/completions. Nos SDKs compatíveis com a OpenAI, trocar a base URL, junto com a chave de API e o ID do modelo, aponta o mesmo código para outro provedor.

[Tool calling (chamada de ferramentas)](https://broadrouter.com/pt/glossary/tool-calling/)

Tool calling, também chamado de function calling ou chamada de ferramentas, é um recurso de APIs de LLM em que o modelo devolve um pedido estruturado para executar uma função definida pelo desenvolvedor, com argumentos JSON. A aplicação executa a função e devolve o resultado; o modelo nunca executa código sozinho.

[Embeddings](https://broadrouter.com/pt/glossary/embeddings/)

Embeddings são listas de números de ponto flutuante (vetores) que um modelo produz para representar um texto, uma imagem ou outra entrada. Entradas com significado parecido recebem vetores próximos, então a distância entre vetores serve para ordenar resultados de busca, agrupar documentos ou encontrar itens relacionados.

[Fala para texto (speech-to-text)](https://broadrouter.com/pt/glossary/speech-to-text/)

Fala para texto, ou reconhecimento automático de fala (ASR), é a tecnologia que converte áudio falado em texto. Uma API de fala para texto recebe um arquivo ou stream de áudio e retorna uma transcrição, normalmente cobrada por minuto de áudio. A precisão é medida pela taxa de erro de palavras e varia com sotaque, dialeto e qualidade da gravação.

[Pagamento por uso (pay-as-you-go)](https://broadrouter.com/pt/glossary/pay-as-you-go/)

Pagamento por uso é um modelo de preço em que você paga só pelo que usa, medido por unidade, como tokens, requisições ou minutos de áudio, sem assinatura nem compromisso mínimo. A maioria das APIs de LLM cobra assim, a partir de um saldo pré-pago ou de uma fatura periódica.

## Perguntas frequentes

### Preciso de outro SDK?

Não. Os SDKs oficiais da OpenAI para Python e Node.js aceitam uma base URL personalizada. Frameworks construídos sobre eles, como o ChatOpenAI do LangChain, também aceitam.

### Como trocar a base URL no SDK da OpenAI?

Passe base\_url para o client em Python ou baseURL em Node.js, ou defina a variável de ambiente OPENAI\_BASE\_URL. Na BroadNet Inference o valor é https://inference.broadnet.ai/v1, e a chave vai em api\_key.

### Por que recebo resposta vazia depois de trocar?

Modelos de raciocínio como DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B pensam antes de responder, e esse raciocínio conta no max\_tokens. Aumente o max\_tokens para 1.000 ou mais, ou defina reasoning\_effort como low.

### Por que recebo erro 404 ou "model not found" depois de trocar?

Normalmente o ID do modelo ainda é o nome do provedor antigo, ou falta o caminho /v1 na base URL. Use o ID exato do novo provedor e a base URL completa.

### Quais erros devo repetir?

Repita 429 e 5xx com backoff exponencial limitado. Corrija 401, 402 e 413 antes de tentar de novo. O guia de erros deste site lista todos os códigos.

### Compatível com a OpenAI é o mesmo que idêntico?

Não. O formato de requisição e resposta é o mesmo, mas IDs de modelo, parâmetros suportados, limites, campos de usage e detalhes de erro podem mudar. Teste cada recurso que o seu app usa.

## Continue lendo

-   [Base URL de APIs compatíveis com a OpenAI: 14 provedores conferidos](https://broadrouter.com/pt/blog/openai-compatible-api-base-urls/)
-   [OpenRouter ou preço fixo para agentes de IA: qual sai mais barato?](https://broadrouter.com/pt/blog/openrouter-alternative-flat-rate/)
-   [Quando vale a pena uma janela de contexto de 1M de tokens (ou não)](https://broadrouter.com/pt/blog/million-token-context-window-guide/)
-   [API de LLM com retenção zero de dados: checklist de 10 perguntas](https://broadrouter.com/pt/blog/zero-data-retention-llm-api-checklist/)
-   [Hardware de GPU e serving da BroadNet, segundo a própria BroadNet](https://broadrouter.com/pt/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache de respostas de LLM para cortar custo: um cache exato em Python](https://broadrouter.com/pt/blog/cache-llm-responses-cut-cost/)
-   [Guia: Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)
-   [Guia: Como usar o SDK Node.js da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-node-sdk/)
-   [Guia: Como usar o LangChain com a BroadNet Inference](https://broadrouter.com/pt/guides/langchain-openai-base-url/)
-   [Guia: Códigos de erro da BroadNet Inference e quando tentar de novo](https://broadrouter.com/pt/guides/errors-and-retries/)
-   [Guia: Streaming de chat completions e conexões que caem](https://broadrouter.com/pt/guides/streaming-chat-completions/)
-   [Guia: Por que um modelo de raciocínio devolve uma resposta vazia](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/)
-   [Guia: Como rotear o LiteLLM para a BroadNet Inference (SDK e proxy)](https://broadrouter.com/pt/guides/litellm-proxy-custom-provider/)

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

[Começar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-openai-compatible-api-migration-checklist&utm_content=page-cta) ·

**Fontes**

-   [Referência da API da BroadNet Inference (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-blog-openai-compatible-api-migration-checklist&utm_content=sources)
-   [README do SDK Python da OpenAI (base\_url, OPENAI\_BASE\_URL, retries; conferido em 2026-11-14)](https://github.com/openai/openai-python)
