Guia de integração

Como se conectar à BestRelay, em um prefácio e seis capítulos

Duas configurações definem tudo: para onde seu cliente envia as requisições e qual chave envia com elas. Este guia traz os valores exatos para cada protocolo.

Prefácio: o que este guia abrange

Seja qual for o cliente, a configuração se resume aos mesmos dois campos: o endereço para onde vão as requisições e a chave que as acompanha. Os capítulos abaixo apresentam os valores para cada protocolo e, em seguida, explicam como as chamadas são cobradas e quais códigos de status você pode encontrar.

Leia o primeiro capítulo independentemente da ferramenta que usar; depois, siga para o capítulo dedicado a ela.

I. A chave e o endereço base

Crie uma chave na seção Chaves de API do painel. Todo o tráfego de API passa por um único host, separado do site:

https://api.bestapirelay.com

A forma de informar o host depende do protocolo usado pelo seu cliente:

Clientes e SDKs compatíveis com OpenAI: o host seguido de /v1, com a chave enviada como token Bearer.
Clientes Anthropic, como Claude Code e Claude Desktop: apenas o host, com a chave em x-api-key ou ANTHROPIC_AUTH_TOKEN.
Clientes Gemini: apenas o host, com a chave em x-goog-api-key.

II. Chamadas compatíveis com OpenAI: cURL, SDKs e Codex

As requisições de chat são enviadas para /v1/chat/completions, e as da Responses API, para /v1/responses. Uma primeira chamada pelo terminal confirma que a chave funciona:

curl https://api.bestapirelay.com/v1/chat/completions \
  -H "Authorization: Bearer bsr_your_key_here" -H "Content-Type: application/json" \
  -d '{"model": "gpt-6.1-sol", "messages": [{"role": "user", "content": "Describe a well-made fountain pen in one sentence."}]}'

No código, configure qualquer SDK da OpenAI para usar a mesma URL base. Com o cliente assíncrono de Python, fica assim:

import asyncio
from openai import AsyncOpenAI

bestrelay_client = AsyncOpenAI(base_url="https://api.bestapirelay.com/v1", api_key="bsr_your_key_here")

async def ask_the_atelier():
    fountain_pen = await bestrelay_client.chat.completions.create(
        model="gpt-6.1-sol",
        messages=[{"role": "user", "content": "Describe a well-made fountain pen in one sentence."}],
    )
    print(fountain_pen.choices[0].message.content)

asyncio.run(ask_the_atelier())

O Codex lê a configuração do provedor em um arquivo:

# ~/.codex/config.toml (BestRelay as the provider)
model = "gpt-6.1-sol"            # any GPT id from the rate card
model_provider = "bestrelay"

[model_providers.bestrelay]
name = "BestRelay"
base_url = "https://api.bestapirelay.com/v1"
env_key = "BESTRELAY_API_KEY"      # export BESTRELAY_API_KEY=bsr_your_key_here
wire_api = "responses"             # Codex speaks the Responses API

Identificadores GPT recomendados: gpt-6.1-sol, gpt-6-astra, gpt-5.6-sol

III. A rota nativa do Gemini

O Gemini CLI usa apenas o endereço do host como URL base (não acrescente /v1beta) e sua chave BestRelay como GEMINI_API_KEY:

export GOOGLE_GEMINI_BASE_URL=https://api.bestapirelay.com
export GEMINI_API_KEY=bsr_your_key_here
gemini

Chamadas diretas usam a rota nativa generateContent, com a chave no cabeçalho x-goog-api-key:

curl "https://api.bestapirelay.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: bsr_your_key_here" -H "Content-Type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Which printing press came first?"}]}]}'

Os modelos Gemini aceitam apenas seu protocolo nativo. Para streaming, use :streamGenerateContent?alt=sse; a rota /v1/chat/completions, no padrão OpenAI, não dá acesso a eles.

IDs dos modelos Gemini para envio: gemini-3.1-pro, gemini-4-argon, gemini-3.8-flash, gemini-2.5-flash

IV. Claude Code e Claude Desktop

Defina duas variáveis de ambiente e inicie o Claude Code como de costume. A URL base é apenas o endereço do host, sem /v1:

export ANTHROPIC_BASE_URL=https://api.bestapirelay.com
export ANTHROPIC_AUTH_TOKEN=bsr_your_key_here
claude

No Windows (PowerShell ou cmd), defina as mesmas duas variáveis com setx e abra um novo terminal:

setx ANTHROPIC_BASE_URL https://api.bestapirelay.com
setx ANTHROPIC_AUTH_TOKEN bsr_your_key_here

Os modelos Claude estão disponíveis apenas para os clientes oficiais Claude Code e Claude Desktop, e o provedor exige Claude Code 2.1.285 ou mais recente. GPT, Gemini e as demais famílias funcionam com qualquer cliente ou SDK compatível.

V. Como uma chamada é cobrada

Cada chamada é cobrada uma única vez, após o término da resposta, com base nos tokens de entrada, saída e cache informados pelo provedor, conforme a tabela de preços. Nenhum valor é reservado antecipadamente.

Se uma chamada bem-sucedida vier sem dados de uso, a cobrança será feita por uma estimativa de 2,000 tokens de entrada e 2,000 tokens de saída, com essa indicação no extrato. Se o seu cliente se desconectar durante um streaming, a chamada ainda será cobrada com base no uso informado pelo provedor.

Requisições rejeitadas pelo provedor e requisições de contagem de tokens são registradas com valor zero. Uma última chamada pode deixar o saldo um pouco abaixo de zero; a partir daí, as requisições retornam 402 até que você adicione créditos.

VI. Códigos de status que você pode encontrar

Os erros retornam no formato JSON habitual, com uma mensagem redigida pela BestRelay:

400: A requisição não especifica um modelo, indica um modelo desconhecido ou usa uma rota incompatível com o protocolo do modelo.
401: Nenhuma chave foi enviada, ou a chave é desconhecida ou foi invalidada.
402: O saldo acabou; adicione créditos para continuar.
403: A conta associada à chave está suspensa.
404: Não existe uma rota nesse caminho.
413: O corpo da requisição excede 25 MB.
429: Mais de 120 requisições por minuto com a mesma chave, ou oito chamadas já em andamento na mesma conta.
502: Não foi possível acessar o provedor; nada foi cobrado.
503: A conexão com o provedor desse modelo ainda não foi configurada.