LOAD BALANCE

Roteie suas chaves
sem queimar nenhuma

O Load Balance é um gateway de chaves de API: seu cliente fala com uma chave sk-lb-, e o Load Balance escolhe, requisição a requisição, qual das chaves de provedor cadastradas atende. Aqui você aponta o cliente para o proxy, cadastra as chaves no painel e entende como cada escolha é feita.

Quickstart Visão geral Referência

Chamada de verdade ao proxy: o caminho é /{orgSlug}/{customUrl}/v1/messages, a chave sk-lb- vai no header x-api-key e a resposta volta no formato da API Messages.

bash200 OK

curl -sS https://lb.exemplo.com/acme/meu-cliente/v1/messages \
  -H "x-api-key: sk-lb-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 256,
    "stream": false,
    "messages": [
      { "role": "user", "content": "Responda em uma palavra: pronto" }
    ]
  }'

json200 OK

{
  "id": "msg_01AbCdEfGhIjKlMnOpQrStUv",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [{ "type": "text", "text": "Pronto." }],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": { "input_tokens": 18, "output_tokens": 3 }
}

Aponte o ANTHROPIC_BASE_URL para a mesma URL pública do painel. O Claude Code faz o preflight com HEAD antes da primeira requisição e manda a chave em x-api-key ou Authorization: Bearer.

bash

export ANTHROPIC_BASE_URL="https://lb.exemplo.com/acme/meu-cliente"
export ANTHROPIC_AUTH_TOKEN="sk-lb-..."

PONTO DE PARTIDA

Escolha o que construir

O Load Balance tem duas superfícies, e elas não se misturam: o proxy entrega tráfego, o painel administra chaves.

⇄

Proxy — você manda a requisição

Seu cliente chama o Load Balance com uma chave sk-lb-. O proxy escolhe a chave de provedor, aplica estratégia, cooldown, janelas de uso e failover, e devolve a resposta no formato que o cliente entende.

Quickstart — proxy Referência da API do proxy URLs e grupos de chaves

▦

Painel — você opera chaves e limites

Você cadastra as chaves de provedor, cria os grupos que rotacionam, emite as chaves sk-lb- e acompanha o tráfego em tempo real. Telas de chaves, limites e grupos são restritas a ADMIN.

Quickstart — painel Referência da API de painel Limites de uso

JORNADA

Da ideia à produção

Quatro etapas, na ordem em que você vai precisar delas.

Comece

Construa

Avalie

Opere

MOTOR DE SELEÇÃO

As estratégias

Cada grupo de chaves tem uma estratégia em ApiKeyGroup.strategy. As cinco determinam qual chave atende a próxima requisição.

round_robin default de ApiKeyGroup.strategy

Cursor incremental por grupo, módulo do tamanho da lista. Use quando todas as chaves forem equivalentes e você só quiser distribuir o tráfego.

sem medição default

priority ordem priority asc

Atende sempre a primeira chave disponível em ordem de prioridade. Use quando uma chave tem de ficar na frente e as demais são reserva — um 429 nela cascateia para a próxima.

ordem fixa failover em cascata

rated ttft + latência + erros

Escolhe a chave de menor score de rating, combinando TTFT, latência total e taxa de erro. Use quando a velocidade varia entre as chaves e o TTFT importa no seu produto.

score observado cold-start pela mediana do grupo

hedge hedgeDelayMs

A primária é escolhida como em rated; se ela demorar além do atraso, uma reserva de outra URL entra. Use quando um TTFT alto custa caro e vale gastar uma segunda chave para cortar a cauda.

reserva escalonada nunca duas chaves da mesma URL

race raceSize

Vence a primeira resposta de N concorrentes disparadas ao mesmo tempo, saindo do mesmo ranqueamento. Use quando a latência vale o custo de abrir várias chaves ao mesmo tempo.

concorrentes em t=0 vitória no primeiro chunk

REFERÊNCIA