Migrar do OpenRouter custa uma linha

Altere a sua base URL e coloque uma chave OrcaRouter. Os seus modelos, o seu SDK e o resto do código ficam exatamente como estão — só os ids de router openrouter/ é que mudam de nome.

Três coisas a verificar

Use a base URL certa para o seu SDK — O SDK da OpenAI quer https://api.orcarouter.ai/v1. Os outros dois querem https://api.orcarouter.ai — cada um acrescenta o seu próprio caminho.
Substitua a sua chave de API pela da OrcaRouter — O valor muda — uma chave OpenRouter não autentica aqui —, mas o lugar não: lemos o mesmo cabeçalho que o seu SDK já envia.
Mantenha os nomes dos modelos — Usamos os mesmos nomes vendor/model, por isso anthropic/claude-sonnet-4 funciona tal como está. A excepção são os ids de router openrouter/ do próprio OpenRouter: esses são renomeados.

Antes e depois: a linha que muda

A OrcaRouter fala nativamente as APIs da OpenAI, da Anthropic e do Gemini, por isso mantém o SDK que já usa. Em cada trecho, as linhas que começam com - são para remover e as que começam com + são para adicionar.

OpenAI — Python

  client = OpenAI(
-     base_url="https://openrouter.ai/api/v1",
+     base_url="https://api.orcarouter.ai/v1",
      api_key=ORCAROUTER_API_KEY,
  )

Essa é a única alteração de código. Coloque também uma chave OrcaRouter — os nomes dos modelos, as mensagens e o streaming ficam iguais, a não ser que chame um id de router openrouter/.

Anthropic — Python

  client = Anthropic(
+     base_url="https://api.orcarouter.ai",
      api_key=ORCAROUTER_API_KEY,
  )

Falamos a API da Anthropic de forma nativa, o que o OpenRouter não faz. Se chamava o Claude através do SDK da OpenAI para se adaptar ao OpenRouter, já não precisa.

Gemini — TypeScript

  const ai = new GoogleGenAI({
    apiKey: ORCAROUTER_API_KEY,
+   httpOptions: { baseUrl: "https://api.orcarouter.ai" },
  });

Também falamos a API do Gemini de forma nativa, por isso o SDK da Google funciona sem alterações.

Exemplos completos para cada SDK

Importações, cliente e uma chamada real. Corre tal como está, assim que ORCAROUTER_API_KEY estiver definida no seu ambiente.

OpenAI — Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.orcarouter.ai/v1",
    api_key=os.environ["ORCAROUTER_API_KEY"],
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

OpenAI — TypeScript

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content);

OpenAI — cURL

curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $ORCAROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Anthropic — Python

import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.orcarouter.ai",
    api_key=os.environ["ORCAROUTER_API_KEY"],
)

message = client.messages.create(
    model="anthropic/claude-sonnet-4",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.content[0].text)

Anthropic — TypeScript

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.orcarouter.ai",
  apiKey: process.env.ORCAROUTER_API_KEY,
});

const message = await client.messages.create({
  model: "anthropic/claude-sonnet-4",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});
console.log(message.content[0].text);

Anthropic — cURL

curl https://api.orcarouter.ai/v1/messages \
  -H "x-api-key: $ORCAROUTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Gemini — Python

import os
from google import genai

client = genai.Client(
    api_key=os.environ["ORCAROUTER_API_KEY"],
    http_options={"base_url": "https://api.orcarouter.ai"},
)

response = client.models.generate_content(
    model="google/gemini-2.5-pro",
    contents="Hello",
)
print(response.text)

Gemini — TypeScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.ORCAROUTER_API_KEY,
  httpOptions: { baseUrl: "https://api.orcarouter.ai" },
});

const response = await ai.models.generateContent({
  model: "google/gemini-2.5-pro",
  contents: "Hello",
});
console.log(response.text);

Gemini — cURL

curl "https://api.orcarouter.ai/v1beta/models/google/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: $ORCAROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Hello"}]}]
  }'

IDs de modelo: o que renomear

Usamos os mesmos nomes vendor/model, por isso anthropic/claude-sonnet-4 funciona tal como está. A excepção são os ids de router openrouter/ do próprio OpenRouter: esses são renomeados.

Na OpenRouter	Na OrcaRouter
`openrouter/auto`	`orcarouter/auto`
`openrouter/free`	`orcarouter/free`
Qualquer outro router openrouter/	Sem equivalente — indique um modelo em vez disso
Qualquer ID vendor/model, como anthropic/claude-sonnet-4	O mesmo ID, sem alterações

Diferenças de faturação

Os tokens são cobrados ao preço de tabela de cada fornecedor, sem margem da OrcaRouter — a plataforma é financiada pelos planos, não por uma margem sobre o seu tráfego.
Mesmo endpoint — leia o id no cabeçalho da resposta. Chame /v1/generation exatamente como faz hoje. A única diferença é a origem do id: o cabeçalho de resposta X-Orca-Request-Id em vez do id no corpo.
Recebe o valor efetivamente cobrado, com as contagens de tokens por trás dele. Um 404 pode querer dizer que o pedido ainda não acabou de ser liquidado, por isso repita algumas vezes ao longo de alguns segundos e depois pare — também pode querer dizer que o identificador é desconhecido, que pertence a outra chave, ou que o pedido falhou e este deployment não regista pedidos falhados. Um 501 quer dizer que as consultas de custo estão desligadas neste deployment; os pedidos liquidados enquanto estavam ligadas continuam a poder ser lidos.
Não há endpoint de saldo. O custo por pedido é devolvido pela API. O saldo global está no painel.

Quatro coisas que não fazemos

Melhor saber agora do que descobrir em produção.

Dizer-lhe que fornecedor atendeu um pedido — Para si, o OrcaRouter é um único fornecedor. Não existe campo provider na resposta: é uma decisão, não um descuido.
Deixá-lo fixar ou excluir um fornecedor — O outro lado da mesma decisão. Continua a controlar que modelos experimentamos, através do encaminhamento de recurso acima.
Comprimir o seu prompt — Sem transforms. Nunca descartamos nem encurtamos as suas mensagens para caberem na janela de contexto — corte-as você, se for preciso. O que pode alterá-las é um prompt configurado no canal que atende o seu pedido: um prompt de sistema, ou um modelo cujos turnos são colocados à frente — e, em modo de substituição, isso substitui a sua própria mensagem de sistema.
Oferecer um endpoint de saldo — O custo por pedido é devolvido pela API. O saldo global está no painel.

Perguntas frequentes

A OrcaRouter substitui a OpenRouter sem mais alterações?

Na maioria das integrações, sim. Altere a base URL e substitua a sua chave por uma da OrcaRouter; o SDK, os nomes dos modelos, as mensagens e o streaming ficam iguais. As exceções são os IDs de router openrouter/ próprios da OpenRouter, que são renomeados, e as quatro coisas que a OrcaRouter não faz de propósito, listadas acima.

De que base URL precisa cada SDK?

O SDK da OpenAI quer https://api.orcarouter.ai/v1. Os outros dois querem https://api.orcarouter.ai — cada um acrescenta o seu próprio caminho.

Posso continuar a usar a minha chave de API da OpenRouter?

O valor muda — uma chave OpenRouter não autentica aqui —, mas o lugar não: lemos o mesmo cabeçalho que o seu SDK já envia.

O que substitui openrouter/auto e openrouter/free?

Os routers da OrcaRouter são os de orcarouter/. Dois correspondem directamente aos deles: use orcarouter/auto em vez de openrouter/auto, e orcarouter/free em vez de openrouter/free — a ideia é a mesma nos dois casos, escolhemos um modelo por si no momento do pedido, e o segundo mantém-no no escalão sem custo. Os restantes routers deles não têm contrapartida aqui, por isso indique um modelo concreto.

O encaminhamento de recurso funciona da mesma forma?

Mova models e route para dentro de extra_body. Tudo o resto é igual: liste os seus modelos por ordem de preferência e experimentamo-los um a um. No mínimo 2 modelos, no máximo 5. Vale a pena fazê-lo bem. No nível superior não os lemos, por isso os seus recursos alternativos deixam de funcionar sem aviso; e em instalações que reencaminham o corpo do pedido tal como está, o modelo recebe esses campos a mais e pode recusar a chamada.

Como vejo quanto custou um pedido?

Leia X-Orca-Request-Id na resposta e depois chame /v1/generation. Um 501 quer dizer que as consultas de custo estão desligadas neste deployment.

X-Title e HTTP-Referer continuam a identificar a minha aplicação?

Envie X-Title e a sua aplicação mantém o nome nas suas análises sem qualquer alteração; também lemos os nomes de cabeçalho do próprio OpenRouter. O HTTP-Referer sozinho só identifica a sua aplicação se o domínio for um dos que já reconhecemos, por isso envie um cabeçalho de título se quiser ter a certeza. Esta linha está aqui para que não os remova por engano.

O que acontece a provider e transforms nos meus pedidos?

Não usamos nenhum dos dois. Num canal normal são descartados antes de o pedido chegar ao modelo; num canal configurado para reencaminhar o corpo em bruto são transmitidos, e um fornecedor rigoroso pode recusar o pedido. Retirá-los é a opção segura em qualquer dos casos.

Que endpoints disponibiliza a OrcaRouter?

Tudo o que espera, mais alguns que o OpenRouter não tem. Disponíveis aqui e não na OpenRouter: /v1/messages, /v1beta/models … generateContent, /v1/rerank e /v1/realtime. Não disponíveis: /v1/fine-tunes, GET /v1/files e /v1/images/variations.

Os erros chegam no mesmo formato?

Os erros voltam com a mesma forma que já trata. Aja pelo estado HTTP: repita um 429 quando enviamos Retry-After, recue e repita um 5xx excepto 501 — que significa que não servimos essa chamada de todo — e trate um 4xx numa chamada do relay como algo a corrigir no seu pedido. A excepção é um 404 de /v1/generation: pode significar apenas que o pedido ainda não liquidou, por isso repita-o brevemente. Não leia error.type como a origem: orcarouter_api_error é sempre nosso, mas para algumas falhas nossas enviamos deliberadamente o vocabulário do fornecedor para que o seu SDK siga o ramo habitual — um limite de taxa aplicado por nós e um aplicado pelo modelo dizem ambos rate_limit_error. Cite X-Orca-Request-Id quando precisar que procuremos uma chamada específica.