BroadRouter
Começar

Como migrar da API da OpenAI: o código em Python, Node e cURL

Pela equipe da BroadNet Inference · 6 min de leitura · Publicado em

Troque a base URL, a chave de API e o ID do modelo no cliente. Isso basta para chamadas de Chat Completions. Código na Responses API precisa ser reescrito para Chat Completions: input vira messages, output_text vira choices[0].message.content e as ferramentas perdem um nível de aninhamento. Mantenha os embeddings num cliente separado se o novo provedor não os oferecer e rode um smoke test antes de mover o tráfego.

Mover um app da OpenAI para um provedor compatível com a OpenAI é uma pequena mudança de código se você usa Chat Completions, e uma reescrita se você usa a Responses API. Este post mostra os diffs exatos em Python, Node e cURL, o que fazer com Responses, ferramentas, saída estruturada e embeddings, e um smoke test para rodar antes de mover qualquer tráfego. Os exemplos usam a BroadNet Inference em https://inference.broadnet.ai/v1; os mesmos passos valem para qualquer provedor.

Este é o complemento em código do checklist de migração, que cobre rate limits, erros e o planejamento da virada. Para as base URLs de outros provedores, veja base URLs compatíveis com a OpenAI, conferidas.

O que muda na configuração do cliente?

Três valores: base URL, chave de API e ID do modelo.

Python

import os
from openai import OpenAI

# before: client = OpenAI()  # reads OPENAI_API_KEY, calls api.openai.com
client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)
r = client.chat.completions.create(
    model="broadnet/gemma-4-26b-a4b",          # was e.g. "gpt-..."
    messages=[{"role": "user", "content": "Reply with one short sentence."}],
)
print(r.choices[0].message.content)

Node

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://inference.broadnet.ai/v1",
  apiKey: process.env.BROADNET_API_KEY,
});
const r = await client.chat.completions.create({
  model: "broadnet/gemma-4-26b-a4b",
  messages: [{ role: "user", content: "Reply with one short sentence." }],
});
console.log(r.choices[0].message.content);

cURL

curl https://inference.broadnet.ai/v1/chat/completions \
  -H "Authorization: Bearer $BROADNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"broadnet/gemma-4-26b-a4b","messages":[{"role":"user","content":"Reply with one short sentence."}]}'

Repare no caminho: a base URL já termina em /v1, então o SDK acrescenta /chat/completions. Duplicar o /v1 é o primeiro erro mais comum.

Dá para trocar sem mexer no código?

Sim, para código de Chat Completions. O SDK Python lê OPENAI_BASE_URL quando nenhuma base_url é passada, e o cliente Node usa process.env['OPENAI_BASE_URL'] como padrão de baseURL. Os dois leem OPENAI_API_KEY. Definir duas variáveis de ambiente move todas as chamadas.

E esse também é o risco. Todas as chamadas mudam, incluindo embeddings, moderação, upload de arquivos e qualquer outra coisa que o novo provedor talvez não tenha. Use a troca por variável de ambiente só quando o seu app faz chamadas de chat e nada mais.

E se o meu código usa a Responses API?

Os READMEs dos SDKs da OpenAI agora chamam a Responses API de API principal; o README do Python chama o Chat Completions de “the previous standard (supported indefinitely)” (tradução: o padrão anterior, suportado por tempo indeterminado). Muitos provedores compatíveis implementam só Chat Completions. A BroadNet documenta POST /v1/chat/completions e POST /v1/audio/transcriptions, então as chamadas de Responses precisam ser reescritas. O mapeamento:

Responses API Chat Completions
client.responses.create(...) client.chat.completions.create(...)
instructions="..." Primeira mensagem {"role": "system", "content": "..."}
input="..." ou uma lista de itens messages=[...]
response.output_text response.choices[0].message.content
max_output_tokens max_tokens (documentação da BroadNet) ou max_completion_tokens
text={"format": {...}} response_format={...}
previous_response_id, conversas Reenvie você mesmo o histórico completo de mensagens
Ferramenta {"type": "function", "name": ...} Ferramenta {"type": "function", "function": {"name": ...}}
Item de saída function_call, resposta com function_call_output e call_id message.tool_calls, resposta com role tool e tool_call_id
Ferramentas embutidas (busca na web, busca em arquivos) Não disponíveis; rode a sua própria ferramenta

O antes e o depois de uma chamada simples:

# Before: Responses API
r = client.responses.create(model="gpt-...", instructions="Be brief.", input="What is RAG?")
text = r.output_text

# After: Chat Completions
r = client.chat.completions.create(
    model="broadnet/gemma-4-26b-a4b",
    messages=[{"role": "system", "content": "Be brief."},
              {"role": "user", "content": "What is RAG?"}],
)
text = r.choices[0].message.content

A maior mudança estrutural é o estado. A Responses pode manter o estado da conversa do lado da OpenAI com previous_response_id. O Chat Completions não tem estado no servidor, então o seu código guarda a lista de mensagens e envia tudo a cada turno. Inclua isso no orçamento: o histórico inteiro vira tokens de entrada em cada chamada.

Como mudam as chamadas de ferramentas?

No Chat Completions, a definição de uma ferramenta aninha a função sob a chave function, e a resposta volta como uma mensagem tool:

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_order",
        "description": "Look up an order by ID.",
        "parameters": {"type": "object",
                       "properties": {"order_id": {"type": "string"}},
                       "required": ["order_id"]},
    },
}]
messages = [{"role": "user", "content": "Where is order A-1042?"}]
r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)
msg = r.choices[0].message
if msg.tool_calls:
    messages.append(msg)                                   # keep the assistant turn
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments)         # a JSON string: parse and validate it
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(lookup_order(args["order_id"]))})
    r = client.chat.completions.create(model="broadnet/glm-5.3", messages=messages, tools=tools)

O modelo importa mais que o formato. A documentação da BroadNet lista ferramentas apenas para o GLM 5.3 e o Qwen3.8 27B. Não aponte um loop de ferramentas para um modelo cuja documentação não lista ferramentas, e valide os argumentos antes de executar qualquer coisa. Tool calling com modelos abertos traz um loop completo com validação.

E a saída estruturada?

client.chat.completions.parse(..., response_format=MyPydanticModel) e o zodResponseFormat do Node enviam response_format com um JSON schema. Eles só funcionam se o provedor aceitar esse formato naquele modelo. A BroadNet lista saída estruturada para o GLM 5.3 e o Qwen3.8 27B, mas não informa o parâmetro da requisição. Rode o teste de quatro passos de JSON mode vs json_schema uma vez por modelo e continue validando o resultado do parse, prometa o provedor o que prometer.

O que acontece com os embeddings?

Se você troca a base URL num cliente compartilhado e o provedor não tem endpoint de embeddings, toda chamada client.embeddings.create falha. A BroadNet não vende embeddings. Mantenha dois clientes:

chat = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
embed = OpenAI(api_key=os.environ["OPENAI_API_KEY"])   # or any embeddings provider

vec = embed.embeddings.create(model="text-embedding-3-small", input=query).data[0].embedding
answer = chat.chat.completions.create(model="broadnet/glm-5.3", messages=build_prompt(query, search(vec)))

Nunca misture vetores de dois modelos de embedding no mesmo índice. Se você também trocar de provedor de embeddings, gere de novo os embeddings do corpus inteiro. A calculadora de custo de embeddings mostra quanto isso custa.

O mesmo vale para tudo o que não é chat: geração de imagens, texto para fala, moderação, a Batch API e armazenamento de arquivos. A BroadNet não oferece nenhum deles. A fala para texto, sim, migra: client.audio.transcriptions.create funciona com /v1/audio/transcriptions usando WAV ou MP3 e um campo language (guia de fala para texto em árabe).

Como muda o código de streaming?

A Responses API transmite eventos tipados, como response.output_text.delta e response.completed. O Chat Completions transmite chunks, e o texto fica em choices[0].delta.content. O usage não é enviado a menos que você peça, e então chega num chunk final com a lista choices vazia.

// Before (Responses): for await (const e of stream) if (e.type === "response.output_text.delta") out(e.delta);
const stream = await client.chat.completions.create({
  model: "broadnet/gemma-4-26b-a4b",
  messages: [{ role: "user", content: "Count from one to three." }],
  stream: true,
  stream_options: { include_usage: true },
});
for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
  if (chunk.usage) console.log("\ntokens:", chunk.usage.total_tokens);   // last chunk
}

Dois hábitos mantêm o código de stream seguro depois da troca. Proteja o acesso a choices[0], porque o chunk de usage não tem choices. E trate como incompleto um stream que termina antes da linha final data: [DONE]; a documentação da BroadNet diz para registrar o X-Request-ID e decidir se uma nova requisição é segura. Streaming de chat completions traz o padrão completo em Python.

O tratamento de erros e as novas tentativas mudam?

As classes de erro do SDK continuam as mesmas: AuthenticationError para 401, RateLimitError para 429, APIStatusError para o resto. O que muda é o que cada status significa no novo provedor. Na BroadNet, um 401 pode indicar uma franquia de pagamento por uso esgotada, não só uma chave errada, e um 402 indica saldo insuficiente para uma compra. Nenhum dos dois se resolve com uma nova tentativa. Um 429 pode vir do limite de taxa, de concorrência, de tokens por minuto ou de gasto. Tente de novo 429 e 5xx com backoff e corrija todo o resto. O guia de erros e novas tentativas traz a tabela completa.

O SDK repete por padrão erros de conexão, 408, 409, 429 e 5xx duas vezes. Se você adicionar o seu próprio loop de novas tentativas, defina max_retries=0 no cliente para que os dois não se somem.

Quais parâmetros se comportam de forma diferente?

Parâmetro O que verificar
max_tokens / max_completion_tokens A OpenAI descontinua max_tokens; a documentação da BroadNet o usa. Em modelos de raciocínio ele inclui o raciocínio, então valores pequenos devolvem respostas vazias (por quê)
reasoning_effort A BroadNet documenta low; teste outros valores antes de depender deles
stream_options: {"include_usage": true} Documentado pela BroadNet; o usage chega no último chunk
n, logprobs, seed, logit_bias Não estão na documentação da BroadNet; teste ou remova
store, metadata Recursos de armazenamento da OpenAI; remova
Partes de conteúdo image_url Só nos modelos listados com imagens: DeepSeek V4.1 Flash, Qwen3.8 27B, Gemma 4 VL 26B

Como testar a troca?

Rode um smoke test curto contra o novo provedor antes de mover qualquer tráfego. Este verifica chat simples, usage em streaming, o orçamento de raciocínio e a autenticação. Acrescente um caso de chamada de ferramenta se você usa ferramentas.

import os, openai
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)
FAST, REASONING = "broadnet/gemma-4-26b-a4b", "broadnet/qwen3.8-27b"
msg = [{"role": "user", "content": "Reply with the word ok."}]

# 1. Plain chat returns text and usage
r = client.chat.completions.create(model=FAST, messages=msg)
assert r.choices[0].message.content and r.usage.prompt_tokens > 0

# 2. Streaming reports usage in the last chunk
chunks = list(client.chat.completions.create(model=FAST, messages=msg, stream=True,
                                             stream_options={"include_usage": True}))
assert chunks[-1].usage is not None

# 3. A reasoning model needs room: a tiny budget can come back empty
r = client.chat.completions.create(model=REASONING, messages=msg, max_tokens=2000)
assert r.choices[0].finish_reason == "stop" and r.choices[0].message.content

# 4. A bad key raises AuthenticationError (401), which you should not retry
bad = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key="invalid", max_retries=0)
try:
    bad.chat.completions.create(model=FAST, messages=msg)
    raise AssertionError("expected 401")
except openai.AuthenticationError:
    pass
print("smoke test passed")

Depois compare a qualidade, não só o formato. Rode de novo uma amostra de prompts reais nos dois provedores e avalie as respostas; avaliar um LLM antes de trocar mostra como. A ferramenta de migração da OpenAI para a BroadNet ajuda a reescrever um trecho de código e lista os recursos que ele usa.

O que quebra com mais frequência?

  • Uma base URL global que também move os embeddings e as chamadas de arquivos.
  • Helpers exclusivos da Responses, como output_text, esquecidos em código que agora chama Chat Completions.
  • IDs de modelos. Nomes gpt-... não existem em outros lugares. Na BroadNet eles têm o formato broadnet/glm-5.3.
  • Respostas vazias de modelos de raciocínio com max_tokens pequeno.
  • Rate limits. Uma chave de pagamento por uso da BroadNet permite 30 requisições por minuto e 4 em andamento. Jobs em lote precisam de uma fila (como lidar com 429).

Onde a BroadNet Inference se encaixa

A BroadNet Inference combina com apps que usam a OpenAI para chat e transcrição: assistentes, extração, resumo, tradução e fala em árabe. Também combina com apps que querem planos de preço fixo do DeepSeek V4.1 Flash para agentes. É o destino errado se você depende do estado no servidor da Responses API, das ferramentas embutidas, de embeddings, de geração de imagens, de texto para fala, de voz em tempo real ou da Batch API. Leve esses recursos para provedores que os oferecem, ou mantenha-os na OpenAI e mova só as chamadas de chat. O Gemma 4 VL 26B e os dois modelos de transcrição rodam com o crédito inicial de $5; o GLM 5.3, o Qwen3.8 27B e o DeepSeek V4.1 Flash exigem recarga antes.

Perguntas frequentes

Preciso de outro SDK para usar uma API compatível com a OpenAI?

Não. Mantenha o pacote oficial openai e passe outra base_url (Python) ou baseURL (Node), mais a chave do novo provedor. Os objetos de requisição e resposta continuam os mesmos nos endpoints que o provedor suporta.

Uma API compatível com a OpenAI suporta a Responses API?

Algumas sim; muitas suportam só Chat Completions. Confira a lista de endpoints do provedor. A BroadNet Inference documenta /v1/chat/completions e /v1/audio/transcriptions, então o código de Responses precisa ser reescrito para Chat Completions.

O que acontece com os meus embeddings quando eu troco?

Eles quebram se o novo provedor não tem endpoint de embeddings e você trocou a base URL globalmente. A BroadNet não vende embeddings, então mantenha um cliente de embeddings apontando para o seu provedor de embeddings. Nunca misture vetores de dois modelos de embedding no mesmo índice.

Devo enviar max_tokens ou max_completion_tokens?

A OpenAI marca max_tokens como descontinuado em favor de max_completion_tokens. Muitos provedores compatíveis documentam max_tokens, e a documentação da BroadNet usa max_tokens. Envie o que o provedor documenta e confirme no smoke test que o limite é aplicado.

Os helpers de saída estruturada da OpenAI continuam funcionando?

Só se o provedor aceitar response_format com json_schema no modelo que você usa. A BroadNet lista saída estruturada para o GLM 5.3 e o Qwen3.8 27B, mas não informa o parâmetro da requisição, então teste e continue validando o resultado do parse.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity