Roteamento transparente e detalhamento da execução

A GetVibe é um roteador transparente: você escolhe explicitamente uma variante pública por meio do sufixo :alias, ou deixa o nome do modelo sem sufixo; nesse caso, o gateway escolhe a rota de acordo com a estratégia da sua conta/chave e, em caso de falhas, muda para outra variante disponível. Somente identificadores de rota públicos são usados nas respostas e no histórico.

"model": "claude-opus-4.8"          // auto — key strategy
"model": "claude-opus-4.8:yellow"   // pin — :yellow only, no switching to other channels
"model": "claude-opus-4.8:2"        // pin — catalog variant #2 (legacy :N syntax)

Cada modelo é fornecido por vários canais com preços diferentes, formando uma escada. Esses dois parâmetros do corpo da solicitação informam quais degraus dessa escada podem atender você. Ambos são USD por 1M de tokens, a mesma unidade e os mesmos números exibidos na página Models. Eles são comparados com o preço que cobramos de você, nunca com um valor de atacado que você não pode ver.

{
  "model": "deepseek-v4-flash-0731",
  "messages": [{"role": "user", "content": "hi"}],
  "max_price": 0.02,
  "min_price": {"input": 0.001}
}

As duas partes precisam se encaixar, entrada e saída — nunca uma média entre as duas. Um canal barato na entrada e caro na saída não atende a um limite de valor único.

Um limite permanente, definido uma vez no painel

Um teto não precisa ser repetido em todas as chamadas. O dashboard armazena um por chave de API e por modelo, além de um padrão que abrange todos os modelos para os quais você não definiu um valor explicitamente, e a API o lê em todas as solicitações. Uma solicitação que inclui max_price usa esse valor em vez disso apenas nessa chamada; uma solicitação que não inclui nenhum valor usa o teto armazenado. Precedência, da mais específica para a menos específica:

Onde ler os preços que você está delimitando

GET /api/catalog publica um array channels para cada modelo: uma entrada por canal em que uma solicitação pode ser processada, do mais barato ao mais caro, cada uma com o endereço pelo qual você pode fixá-la, seu preço de inputUsd / outputUsd por 1M de tokens e se é o padrão. Esses são os números exatos contra os quais max_price e min_price são comparados e os números exatos pelos quais você é cobrado — uma lista, não três.

curl -s https://getvibeapi.com/api/catalog   | jq '.[] | select(.apiModel=="z-ai/glm-5.3") | .channels'

O que é cobrado de você

Você é cobrado pelo canal que realmente atendeu à solicitação, mais nossa margem fixa — não pelo teto que você definiu, e nunca mais do que ele. Se você limitar a um preço e a solicitação for atendida em um nível mais barato, pagará o preço mais barato. A escala na página do modelo mostra uma faixa, e o valor “a partir de” é o nível mais barato existente — é um preço real que poderia ser cobrado de você, não uma promessa de que esta solicitação chegará a ele. Defina max_price quando precisar de um limite superior garantido.

Quando nada se encaixa

A solicitação é recusada: HTTP 422 com "type": "price_bound_no_lane", citando os preços mais baixo e mais alto dos canais para esse modelo e a lista completa de channels, para que você possa escolher um limite com base nos números em vez de tentar adivinhar um. lowest_passing_usd_per_million é o menor limite que admite um canal neste momento — o próprio par de um canal; portanto, enviá-lo funciona (as duas etapas cheapest podem vir de canais diferentes). O mesmo campo aparece quando a própria exchange recusou seu limite: nesse caso, ele é o próximo nível de preço que ainda tem oferta e nunca é inferior ao limite enviado. Quando seu limite não era o fator limitante — o nosso próprio teto de compra para o canal era, e as ofertas abaixo dele estavam ocupadas ou esgotadas — a resposta é HTTP 503 "type": "no_seller_available" com Retry-After e sem preço sugerido: aumentar max_price não ajudaria; tentar novamente em breve talvez ajude. O degrau mais barato geralmente contém uma única oferta que está ocupada; portanto, para preenchimentos confiáveis, defina o limite no nível ou acima do priceTypical do modelo, onde está a maior parte da oferta. Nunca fornecemos silenciosamente um canal mais caro e nunca substituímos outro modelo. Um valor malformado — uma string, zero, um número negativo ou um campo desconhecido — é 400 invalid_request_error, nunca ignorado silenciosamente.

{
  "error": {
    "message": "No channel of model "deepseek-v4-flash-0731" is priced within your max_price $0.0001 in / $0.0001 out...",
    "type": "price_bound_no_lane",
    "code": 422,
    "param": "max_price",
    "cheapest_usd_per_million": {"input": 0.0065, "output": 0.013},
    "dearest_usd_per_million": {"input": 0.0528, "output": 0.1584},
    "lowest_passing_usd_per_million": {"input": 0.0205, "output": 0.0613},
    "channels": [
      {"address": "deepseek/deepseek-v4-flash-0731:codebuddy-cn", "label": "codebuddy-cn", "inputUsd": 0.0205, "outputUsd": 0.0613, "isDefault": true},
      {"address": "deepseek/deepseek-v4-flash-0731:qwencloud", "label": "qwencloud", "inputUsd": 0.0378, "outputUsd": 0.1132, "isDefault": false}
    ]
  }
}

Os canais atendidos por um pool de assinatura do fornecedor podem ser endereçados pelo nome. Escreva o nome depois de dois-pontos, exatamente como qualquer outro alias:

"model": "gpt-6.1-sol:codex"         // pin a subscription pool
"model": "claude-opus-5.5:claude-code"  // pin the Claude Code pool

O sufixo após os dois-pontos é um identificador de rota público, não um nome upstream. A lista completa para um modelo específico está no catálogo (Models, na coluna «In API»). Principais aliases:

Para solicitações auto (modelo sem especificação), os itens a seguir são definidos em cada chave de API (dashboard → API keys):

Adicione um alias de fornecedor após dois-pontos — ele será respeitado independentemente da estratégia de roteamento. A lista completa de aliases e exemplos está na seção Models → Providers.

"model": "claude-opus-4.8"        // auto — key strategy
"model": "claude-opus-4.8:yellow"     // explicitly pin the :yellow channel
"model": "claude-opus-4.8:kiro-pool"  // explicitly pin the :kiro-pool channel

Para cada chave de API, você pode definir no dashboard:

Com um modelo simples, o gateway pode mudar para outra variante pública do mesmo modelo se a atual retornar 429, 5xx ou um 200 vazio sem conteúdo. Restrições:

• Solicitações com imagens/PDF não são direcionadas a outro provedor (compatibilidade com visão).
• O failover não usa uma variante significativamente mais cara (exceto strategy=price).
• Há um limite superior para o número de tentativas por solicitação do cliente.
• Com pin (:alias), o failover entre fornecedores fica desativado — você recebe o erro da rota escolhida.

A tentativa novamente com espera exponencial em 429 é descrita em Erros e limites.

Para clientes confiáveis de reveal/debug, após a conclusão da solicitação (incluindo auto), os cabeçalhos ficam disponíveis e mostram qual variante pública foi realmente executada. Clientes comuns não recebem esses dados.

Cabeçalhos de resposta para clientes confiáveis de reveal/debug (chat / messages / responses)

curl -sD - https://getvibeapi.com/v1/chat/completions \
  -H "Authorization: Bearer $GETVIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6.1-sol","messages":[{"role":"user","content":"ping"}],"max_tokens":8}' \
  -o /dev/null | grep -i getvibe

# x-getvibe-route: yellow
# x-getvibe-model: gpt-6.1-sol:yellow

Histórico de uso

Em GET /v1/generations, GET /v1/usage e no dashboard, cada registro tem os campos:

A GetVibe não fornece uma listagem «raw» em cascata dos provedores upstream no corpo da solicitação. O controle é feito por meio de :alias público, estratégia de chave e failover automático dentro do catálogo de modelos. Não existe uma API separada de «ignorar provedores» nem flags de ZDR de roteamento.