PT ▾
Obter chave de API

Endpoint compatível com OpenAI para clientes OpenRouter

Um endpoint compatível com OpenAI do OpenRouter é apenas uma URL base que fala o formato de chat da OpenAI, então trocá-lo por outro leva algumas linhas. Aqui estão os valores exatos, os formatos de solicitação e os erros que você pode encontrar.

Atualizado

Um único cabo conectando um terminal a um cubo de modelo brilhante, representando um endpoint de API substituído

Pontos principais

  • A URL base é https://api.openrouteralternativeapi.com/v1 e o ID do modelo é uncensored.
  • A autenticação é um cabeçalho Bearer padrão; apenas POST /v1/chat/completions e GET /v1/models existem.
  • Streaming, ferramentas e modo JSON funcionam, mas campos exclusivos do roteador não são suportados.
  • No HTTP 429, leia o código de erro para distinguir um limite de taxa de um limite de concorrência.

Os valores que você precisa

Qualquer ferramenta que permita editar um endpoint estilo OpenAI precisa de três valores. Copie-os da tabela e nada mais muda em uma configuração típica.

ConfiguraçãoValor
URL basehttps://api.openrouteralternativeapi.com/v1
Chave de APICriado na página da chave de API
ID do modelouncensored
Cabeçalho de autenticaçãoAuthorization: Bearer YOUR_API_KEY
Endpoint de chatPOST /v1/chat/completions
Rota de lista de modelosGET /v1/models

A URL base já termina com /v1. A maioria dos SDKs adiciona /chat/completions automaticamente, então não a adicione duas vezes. Algumas ferramentas pedem a rota completa de chat; nesse caso, use a URL base seguida por /chat/completions.

O que o endpoint é e não é

Por trás da URL está um único modelo de pesos abertos, executado por um provedor independente e ajustado para responder sem recusas de conteúdo para uso adulto legal. Não é um roteador, então uma requisição nunca é encaminhada para outro fornecedor. Também não é a API oficial de nenhum fabricante de modelo. Isso importa para a configuração: não há lista de slugs de modelo para escolher, campo de preferência de provedor ou cadeia de fallback. Você envia uncensored e recebe esse único modelo.

O serviço é apenas texto. Geração de imagem, áudio, vídeo, embeddings e ajuste fino não são oferecidos, então um cliente que chama /v1/embeddings ou uma rota de imagens falhará nesta URL base. Mantenha essas chamadas apontadas para o serviço que você já usa para elas, e defina a URL base por recurso em vez de globalmente se seu aplicativo misturar vários.

Mais um ponto de compatibilidade diz respeito à lista de modelos. Um cliente que chama GET /v1/models na inicialização, para preencher uma lista suspensa ou validar uma configuração, receberá o único modelo de volta. Isso é esperado. Se seu código verifica se um nome de modelo configurado aparece na lista, defina o nome para uncensored e a verificação passará. Se seu aplicativo codifica um nome de modelo de fornecedor em algum lugar profundo em um arquivo de configuração, procure o repositório por ele antes da primeira execução, porque uma string restante é a razão mais comum de um aplicativo migrado ainda falhar após a URL ter sido alterada.

Primeira requisição, três formas

Comece com uma requisição do terminal. Isso prova a chave, a URL e o ID do modelo antes que qualquer framework esteja envolvido.

curl https://api.openrouteralternativeapi.com/v1/models   -H "Authorization: Bearer $API_KEY"

curl https://api.openrouteralternativeapi.com/v1/chat/completions   -H "Authorization: Bearer $API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 10
  }'

A mesma chamada com o SDK Python. Observe que nada além de base_url e api_key difere do código OpenAI padrão.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.openrouteralternativeapi.com/v1",
    api_key="YOUR_API_KEY",
)

r = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Reply with the word ready."}],
    max_tokens=10,
)
print(r.choices[0].message.content)
print(r.usage)

E com Node, lendo a chave de uma variável de ambiente:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.openrouteralternativeapi.com/v1",
  apiKey: process.env.API_KEY,
});

const r = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Reply with the word ready." }],
  max_tokens: 10,
});
console.log(r.choices[0].message.content);

Muitas ferramentas leem variáveis de ambiente em vez de argumentos do construtor. Os SDKs oficiais comumente honram OPENAI_BASE_URL e OPENAI_API_KEY, o que permite redirecionar um script não modificado. Verifique a documentação da sua versão do SDK para confirmar os nomes.

Streaming, ferramentas e modo JSON

Os recursos dos quais a maioria dos clientes depende estão presentes. Defina stream: true para receber eventos enviados pelo servidor; o uso é relatado no final do stream. Chamada de funções aceita tools e tool_choice, streams deltas de tool_calls e espera resultados de volta como mensagens com role: "tool". O modo JSON é habilitado com response_format: {"type":"json_object"}. Os campos de amostragem temperature, top_p, stop, seed e as penalidades de frequência e presença são passados.

Um exemplo de streaming em Python:

stream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Write three short taglines for a coffee cart."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

E o modo JSON, que vale a pena combinar com uma instrução no prompt que nomeia as chaves que você espera:

r = client.chat.completions.create(
    model="uncensored",
    messages=[
        {"role": "system", "content": "Return JSON with keys title and tags (array of strings)."},
        {"role": "user", "content": "Summarise: a guide to brewing cold coffee at home."},
    ],
    response_format={"type": "json_object"},
)
print(r.choices[0].message.content)

Sempre analise o resultado em um bloco try. O modo JSON aumenta as chances de saída válida, mas seu código ainda deve lidar com uma resposta malformada, por exemplo, tentando novamente uma vez.

Conversas multi-turno e chamadas de ferramentas

O endpoint é stateless, como a rota de chat da OpenAI. Ele não lembra chamadas anteriores, então cada requisição deve carregar a conversa que você quer que o modelo veja. Mantenha uma lista de mensagens, anexe a resposta do assistente após cada turno e envie a lista inteira novamente. Cuidado com o total: a janela de 100.000 tokens cobre prompt mais conclusão, e históricos longos também são o que impulsionam o custo de entrada.

history = [{"role": "system", "content": "You answer in two sentences."}]

def chat(text):
    history.append({"role": "user", "content": text})
    r = client.chat.completions.create(model="uncensored", messages=history)
    reply = r.choices[0].message.content
    history.append({"role": "assistant", "content": reply})
    return reply

Para chamada de funções, descreva suas funções em tools, execute o que o modelo pedir e envie a saída de volta como uma mensagem de role: "tool" que carrega o tool_call_id correspondente. Uma definição mínima se parece com isto:

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Look up an order by its number",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

r = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Where is order 1042?"}],
    tools=tools,
    tool_choice="auto",
)
call = r.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)

Valide os argumentos antes de executar qualquer coisa. O modelo propõe uma chamada; seu código decide se é seguro executá-la, especialmente quando a função toca dinheiro, arquivos ou dados de outras pessoas.

Campos a remover de requisições estilo OpenRouter

Clientes escritos para um roteador frequentemente adicionam extras ao corpo da requisição ou cabeçalhos. Exemplos típicos são ordenação de provedores, matrizes de fallback do modelo, preferências de roteamento e cabeçalhos de atribuição. Esta API não os usa. Campos desconhecidos podem ser ignorados ou causar um erro, dependendo do campo, então remova-os em vez de confiar em qualquer resultado.

  • Substitua qualquer slug de modelo que inclua um prefixo de fornecedor por uncensored.
  • Remova listas de fallback. Se o único modelo estiver indisponível, trate-o na sua própria lógica de retry.
  • Não envie partes de conteúdo de imagem ou áudio. O modelo lê texto.
  • Mantenha o corpo total da requisição abaixo de 8 MB.

A página de documentação mostra os parâmetros que são suportados, e é o lugar para verificar quando um campo se comporta de forma diferente do que seu cliente espera.

Limites e as respostas 429

Uma chave completa permite 8 requisições concorrentes e 300 requisições por minuto; uma chave de teste permite 2 e 60. Cada resposta carrega X-Request-Id, X-Balance-USD, X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency. Registre o ID da requisição com cada falha, porque é a primeira coisa que o suporte pedirá.

Existem três tipos de HTTP 429. O código de erro rate_limited significa que você excedeu requisições por minuto: diminua a velocidade. O código concurrency significa que muitas requisições estão em andamento ao mesmo tempo: coloque-as em fila. Um 429 com um cabeçalho Retry-After: 5 significa sobrecarga temporária: aguarde cinco segundos e tente novamente. Lembre-se de que uma requisição de streaming mantém sua slot de concorrência até que o stream termine, então um cliente travado que nunca lê até o final consumirá capacidade.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.openrouteralternativeapi.com/v1",
    api_key="YOUR_API_KEY",
    max_retries=0,
)

def ask(prompt, tries=4):
    for i in range(tries):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=[{"role": "user", "content": prompt}],
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            wait = 5 if i == 0 else 5 * (i + 1)
            time.sleep(wait)
    raise RuntimeError("still rate limited")

Defina também um semáforo de 8 ou menos ao redor das chamadas se executar workers em paralelo. Isso é mais barato do que aprender o limite a partir de erros. Adicione um pequeno jitter aleatório à espera para que vários workers que falharam juntos não tentem novamente todos no mesmo segundo. Se você ver respostas 429 repetidas com baixo tráfego, procure por streams que são abertos mas nunca fechados, ou por um loop de retry que é acionado sem esperar, já que qualquer um deles pode preencher as vagas disponíveis por conta própria.

Verificação de custo antes de apontar para produção

O preço é $0,15 por 1M tokens de entrada e $0,50 por 1M tokens de saída de crédito pré-pago. Pegue uma requisição com 2.000 tokens de entrada e 500 tokens de saída. Entrada custa 2.000 / 1.000.000 x $0,15 = $0,0003. Saída custa 500 / 1.000.000 x $0,50 = $0,00025. A requisição custa $0,00055, então 1.000 dessas requisições custam $0,55. Requisições falhas ou recusadas não são cobradas. Veja a página de preços para valores de recarga e bônus; o crédito de teste de $0,50 cobre cerca de 900 requisições desse tamanho (0,50 / 0,00055).

Perguntas e respostas

Qual é a URL base do endpoint compatível com OpenAI?

Use https://api.openrouteralternativeapi.com/v1 como URL base e envie sua chave como token Bearer. O ID do modelo é uncensored.

Quais rotas estão disponíveis?

POST /v1/chat/completions para geração e GET /v1/models para a lista de modelos. Não há rotas de embeddings, imagem, áudio ou ajuste fino.

Preciso alterar meu código além da URL e da chave?

Geralmente apenas a string do modelo. Remova campos específicos do roteador, como preferências de provedor ou listas de fallback, do corpo da requisição.

Por que recebo HTTP 429?

Verifique o código de erro. rate_limited indica muitas requisições por minuto, concurrency indica muitas simultâneas e um cabeçalho Retry-After: 5 indica sobrecarga temporária.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.