Escolhendo um nível de entrega do TokenLab: Auto, Verified ou Official

Uma solicitação pode falhar com um erro 503 mesmo que o ID do modelo seja perfeitamente válido, e a causa geralmente é o nível de entrega que você fixou. Em nosso pipeline, encontramos isso quando forçamos uma opção em um modelo que não a oferecia. Este guia explica as três opções de nível de entrega, a ordem em que as configurações são aplicadas e o que cada uma significa para sua fatura. Todos os fatos abaixo vêm da documentação do TokenLab e da API de modelos em tempo real, observados em 03/10/2026.

Principais conclusões

• Um nível de entrega possui três valores: auto, verified e official.
• Um cabeçalho de solicitação substitui a configuração da chave de API, que substitui o padrão do Workspace.
• Se a opção solicitada não tiver disponibilidade, você receberá 503 delivery_tier_unavailable. Quando retryable for false, não reenvie a mesma solicitação.
• Você paga uma vez, pela opção que completou a solicitação.
• Verifique GET /v1/models/{model} antes de fixar um nível. É público e não precisa de chave.

As três opções de nível de entrega

A referência da API (observada em 03/10/2026) define três opções:

• Auto usa o TokenLab Verified quando disponível, depois o Official, se necessário. Você paga pela opção que completa sua solicitação.
• TokenLab Verified é a entrega verificada pelo TokenLab. Aplicam-se os preços do TokenLab.
• Official baseia-se no preço público do criador do modelo. O preço exibido no TokenLab é o que você paga.

As solicitações de geração aceitam o cabeçalho X-TokenLab-Delivery-Policy: auto | verified | official. Um valor de cabeçalho inválido retorna 400.

Qual configuração é aplicada primeiro

Três locais podem definir o nível de entrega. A ordem documentada é:

1. O cabeçalho da solicitação.
2. A configuração da chave de API.
3. O padrão do Workspace.

O cabeçalho substitui a chave, e a chave substitui o Workspace. As sessões em tempo real são a exceção: elas usam a configuração da chave de API ou do Workspace e não aceitam uma substituição por query-string.

Definir o nível de entrega em uma solicitação

Aqui está uma chamada de Chat Completions que fixa a entrega Official. O ID do modelo claude-sonnet-5 está listado na API de modelos em tempo real com ambas as opções disponíveis. Veja a página do modelo.

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: official" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

O mesmo cabeçalho funciona no endpoint de Mensagens da Anthropic. Para /v1/messages, o cabeçalho da chave pode ser x-api-key, que a referência da API diz que as Mensagens da Anthropic aceitam.

curl https://api.tokenlab.sh/v1/messages \
  -H "x-api-key: $TOKENLAB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -H "X-TokenLab-Delivery-Policy: verified" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Definir o nível de entrega em uma chave de API

Para tornar um nível de entrega o padrão para uma chave, use a API de Gerenciamento com um token de gerenciamento (mt-...). As páginas Criar Chave de API e Atualizar Chave de API (ambas observadas em 03/10/2026) documentam um campo deliveryPolicy. Seus valores são auto, verified, official ou null. Um valor null herda a política do Workspace.

Este esboço segue o formato PATCH documentado. O ID da chave é o valor de exemplo da documentação.

curl -X PATCH "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456" \
  -H "Authorization: Bearer mt-your-management-token" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryPolicy": "verified"
  }'

A atualização requer pelo menos um campo, portanto, este corpo é válido por si só. As respostas relatam a configuração como delivery_policy, onde null significa que a chave herda o padrão do Workspace. O endpoint de criação aceita o mesmo campo deliveryPolicy no corpo da solicitação. Omiti-lo na criação é consistente com a herança null documentada, conforme mostra a resposta de exemplo de criação delivery_policy: null.

Quando a opção solicitada não está disponível

Se a opção que você solicitou não tiver disponibilidade, o TokenLab retorna 503 delivery_tier_unavailable e um ID de solicitação. O guia de tratamento de erros (observado em 03/10/2026) explica como ler retryable.

Um status 5xx nem sempre significa uma interrupção temporária. Quando a operação selecionada não tem disponibilidade nesse nível, retryable é false e retry_after é omitido. Não repita a mesma solicitação sem alterações. Em vez disso:

1. Leia code e retryable, não a message legível por humanos.
2. Salve o ID da solicitação dos cabeçalhos de resposta.
3. Verifique a disponibilidade de entrega do modelo com GET /v1/models antes de escolher outro modelo ou nível.

O guia alerta que nomes de modelos semelhantes não provam disponibilidade. Um cliente deve ramificar com base no code e tentar novamente um 5xx apenas quando retryable for true, respeitando retry_after e limitando as tentativas.

Verificar quais opções um modelo possui

O endpoint de modelos relata a delivery availability by option. Esses valores vêm da API de modelos em tempo real, observada em 03/10/2026:

ID do Modelo	Verified	Official	Página do modelo
claude-sonnet-5	true	true	/models/claude-5/claude-sonnet-5
gpt-5.6-terra	true	true	/models/gpt-5-6/gpt-5.6-terra
deepseek-v4-flash	false	true	/models/deepseek-v4/deepseek-v4-flash

Por exemplo, fixar verified no deepseek-v4-flash é o tipo de solicitação que atingiria delivery_tier_unavailable, porque a API não relata disponibilidade Verified hoje. Official e Auto permanecem válidos lá.

Verifique qualquer modelo você mesmo:

curl "https://api.tokenlab.sh/v1/models/deepseek-v4-flash"

A disponibilidade é verificada quando cada solicitação é executada, e o guia de Faturamento diz que os rótulos de entrega descrevem as opções suportadas. Trate a API de modelos como um instantâneo e releia-a antes de fixar um nível permanentemente.

Como a escolha afeta o que você paga

O guia de Faturamento (observado em 03/10/2026) diz que cada solicitação concluída é cobrada uma vez, pela opção que produziu o resultado:

• TokenLab Verified usa os preços públicos do TokenLab.
• Official usa a camada de preço Official baseada no preço público do criador do modelo.
• Auto cobra a opção que completar a solicitação.

Para geração paga, o Console mostra uma estimativa máxima antes da confirmação, e o Uso mostra a cobrança final. Qualquer valor reservado não utilizado é liberado. Na página de Modelos, um traço na coluna de preço do TokenLab significa que nenhuma oferta Verified está disponível no momento. Não significa que é gratuito.

O guia não documenta uma diferença de preço fixa entre Verified e Official, portanto, não reivindicaremos uma. Para o preço do TokenLab em tempo real no claude-sonnet-5, a API de modelos lista a entrada a 0,9 USD e a saída a 4,5 USD por 1 milhão de tokens (preços atualizados em 02/10/2026). Como estimativa, 100.000 tokens de entrada mais 10.000 tokens de saída resultam em 0,09 + 0,045 = 0,135 USD. Esse valor usa apenas o preço listado do TokenLab. Leia o preço Official na página do modelo antes de comparar.

Um breve guia de decisão

• Use Auto como padrão quando quiser que a solicitação seja concluída e puder aceitar qualquer uma das camadas de preço.
• Fixe Verified quando precisar dos preços do TokenLab e o modelo relatar verified: true.
• Fixe Official quando precisar da base de preço público do criador do modelo, ou quando o modelo não tiver disponibilidade Verified.
• Defina o padrão da chave para workers que sempre precisam do mesmo nível, e use o cabeçalho para exceções pontuais.

Antes de fixar, leia GET /v1/models/{model}. Execute um pequeno teste e confirme a cobrança em Uso.

Próximo passo: criar uma chave com uma política de entrega

Crie uma chave de API no Console, ou chame POST /v1/management/api-keys com um token de gerenciamento e defina deliveryPolicy no corpo, conforme descrito na página Criar Chave de API. Em seguida, envie uma pequena solicitação com o cabeçalho acima e verifique a cobrança em Uso.

FAQ

Qual configuração vence se o cabeçalho, a chave de API e o Workspace discordarem?

O cabeçalho da solicitação vence. A configuração da chave de API substitui o padrão do Workspace. As sessões em tempo real ignoram o cabeçalho e usam a configuração da chave ou do Workspace.

Por que recebi 503 delivery_tier_unavailable e devo tentar novamente?

O nível que você solicitou não tem disponibilidade para essa operação. Leia retryable: quando for false, não reenvie a mesma solicitação. Verifique a disponibilidade com GET /v1/models e altere o nível ou o modelo.

O Official custa mais do que o TokenLab Verified?

A documentação não declara uma diferença fixa. O Verified usa os preços públicos do TokenLab, e o Official usa a base de preço público do criador do modelo. Compare os dois na página do modelo e confirme a cobrança final em Uso.

Como vejo quais opções de entrega um modelo suporta?

Chame GET /v1/models/{model}, que não precisa de chave. Hoje, claude-sonnet-5 e gpt-5.6-terra relatam Verified e Official, enquanto deepseek-v4-flash relata apenas Official.

Posso definir uma opção de entrega para sessões em tempo real?

Sim, através da chave de API ou da configuração do Workspace. As sessões em tempo real não aceitam uma substituição por query-string.

Crie sua chave de API do TokenLab no Console