Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Cabeçalhos da API e Gestão de Excedentes

Aula 8 de 14 Atualizada a 28 de julho de 2026 Intermediario
Nesta página
  1. Decida quais pedidos consomem a sua capacidade
  2. Contornar voluntariamente a capacidade dedicada
  3. Encaminhar um pedido para um pool específico
  4. O que acontece em caso de excedente
  5. Traduzir a prioridade em código da aplicação
  6. Pontos-chave

Decida quais pedidos consomem a sua capacidade

Reservar capacidade resolve apenas metade do problema: ainda precisa de escolher quais os pedidos que realmente beneficiam dessa reserva. O throughput provisionado não é uma compra global que faz uma vez no início do mês; é um mecanismo que controla chamada a chamada. A xAI expõe cabeçalhos HTTP dedicados para este fim, que arbitram, pedido a pedido, entre a sua capacidade dedicada e o pool partilhado. Uma alocação fixa torna-se assim uma alavanca operacional que as suas equipas manipulam diretamente no código da aplicação.

Contornar voluntariamente a capacidade dedicada

O primeiro cabeçalho serve para excluir um pedido da sua alocação:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "x-pt-disable: true" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [{"role": "user", "content": "Summarize this document."}]
  }'

Renunciar à sua própria capacidade pode parecer contraproducente. Quatro situações justificam-no nas operações diárias. Primeiro, tarefas não críticas: uma análise em lote lançada às 22h ou um trabalho de processamento diferido não necessita de garantia de latência, e seria uma pena que consumisse a alocação paga para tráfego interativo. Segundo, preservar a capacidade durante picos: ao desativar o throughput provisionado no processamento secundário, liberta alocação exatamente quando chegam pedidos prioritários em grande volume. O cabeçalho também serve para testes A/B, quando quer medir a diferença real de desempenho entre capacidade dedicada e partilhada na sua própria carga, e não numa promessa do fornecedor. Por fim, é valioso para depuração: forçar o pedido através do pool partilhado indica-lhe imediatamente se a anomalia observada provém da capacidade provisionada ou do seu código.

Encaminhar um pedido para um pool específico

O segundo cabeçalho direciona a chamada para um pool de capacidade identificado:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "x-pt-id: pool-support-client" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [{"role": "user", "content": "How can I help you?"}]
  }'

Este cabeçalho torna-se indispensável assim que várias aplicações na sua organização chamam o Grok. Cria então pools separados — um pool-support para o chatbot de apoio ao cliente, um pool-analysis para análise de documentos, um pool-internal para ferramentas de negócio — e cada um opera de forma independente. A segmentação isola o desempenho: a campanha de análise de documentos lançada numa segunda-feira de manhã já não degrada os tempos de resposta do apoio. Produz também um consumo desagregado por utilização, oferecendo assim uma base factual para imputação de custos ou arbitragem, onde antes dependia de estimativas. E impede, inerentemente, que uma única aplicação monopolize a capacidade em detrimento das outras.

O que acontece em caso de excedente

Quando o tráfego excede a capacidade provisionada, o mecanismo de fallback é automático e silencioso: o pedido vai para o pool partilhado em regime de pagamento conforme o uso («pay-as-you-go»), aplicam-se as tarifas padrão do modelo e fica sujeito aos limites de taxa habituais. Nenhum erro é devolvido; a sua aplicação não deteta qualquer alteração.

Esta discrição tem duas faces. Do lado da disponibilidade, a notícia é boa: nunca encontrará um erro 429 causado pela excedência da capacidade provisionada. Do lado financeiro e da qualidade de serviço, é menos boa. O pedido é faturado à tarifa «pay-as-you-go», potencialmente mais elevada; os tempos de resposta podem variar, uma vez que o processamento ocorre em infraestrutura partilhada; e, acima de tudo, o SLA de 99,9% cobre apenas os pedidos processados dentro do throughput provisionado. Um excedente, portanto, não quebra nada; simplesmente faz com que saia discretamente do âmbito pelo qual paga. A API de Gestão expõe a proporção de pedidos processados em modo provisionado versus «pay-as-you-go»: examine este rácio todos os meses tal como examina uma fatura. Uma taxa de excedente em ascensão é o sinal de que precisa de aumentar a alocação.

Traduzir a prioridade em código da aplicação

Em vez de multiplicar funções de chamada, a prática mais sólida consiste em qualificar a prioridade no momento em que o pedido é emitido:

import httpx

def query_grok(prompt: str, priority: str = "normal"):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }

    if priority == "low":
        headers["x-pt-disable"] = "true"
    elif priority == "high":
        headers["x-pt-id"] = "pool-critical"

    response = httpx.post(
        "https://api.x.ai/v1/chat/completions",
        headers=headers,
        json={
            "model": "grok-4.3",
            "messages": [{"role": "user", "content": prompt}],
        },
    )
    return response.json()

O parâmetro priority torna-se a única decisão exposta à lógica de negócio, e a política de encaminhamento permanece concentrada numa única função que evolui sem tocar no resto. Reveja o seu próprio código de chamada e classifique cada ponto de entrada numa de três categorias: o exercício mostra regularmente que uma boa metade do tráfego não necessitava de capacidade dedicada.

Pontos-chave

  • O cabeçalho x-pt-disable: true contorna a capacidade provisionada para um pedido
  • O cabeçalho x-pt-id encaminha para um pool de capacidade específico
  • Os excedentes recorrem automaticamente ao regime «pay-as-you-go» sem gerar erros
  • A segmentação em pools permite isolar o desempenho e rastrear o consumo por aplicação
  • Monitore a taxa de excedentes para ajustar a sua alocação, se necessário