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

Endpoint de tokenização e ferramentas

Aula 6 de 14 Atualizada a 29 de julho de 2026 Avancado
Nesta página
  1. Contar tokens antes do envio
  2. O endpoint /v1/tokenize-text
  3. A ferramenta visual da consola
  4. Onde colocar a contagem num pipeline
  5. Ferramentas integradas, uma rubrica separada
  6. Pontos-chave

Contar tokens antes do envio

Três questões surgem antes de qualquer chamada API séria: o seu prompt cabe na janela de contexto? Quanto vai custar? Onde deve cortar se o documento for demasiado longo? Responder a estas perguntas depois do envio — quando vê um erro ou recebe a fatura — custa sempre mais do que respondê-las antecipadamente. A API Grok fornece exatamente a ferramenta para isto: um endpoint de tokenização, gratuito e desacoplado das conclusões.

O endpoint /v1/tokenize-text

POST /v1/tokenize-text aceita texto bruto e devolve a contagem de tokens correspondente. A funcionalidade chave resume-se a uma frase: ao contrário de uma chamada de conclusão, este endpoint não consome tokens faturados. Ele conta; não gera.

curl -X POST "https://api.x.ai/v1/tokenize-text" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your text to tokenize here."
  }'

A resposta fornece a contagem total de tokens e, dependendo da versão, a desagregação dos tokens individuais. Daqui decorrem diretamente três utilizações. Primeiro, validação: verifica se a soma do prompt do sistema, do histórico e da mensagem do utilizador se mantém dentro da janela do modelo alvo — 1 milhão de tokens no grok-4.3 e 500.000 no grok-4.5. Seguidamente, estimativa de custos: o número resultante, multiplicado pela tarifa do modelo, indica o preço do pedido antes de o confirmar. Por fim, truncagem: para um documento de dimensão excessiva, a tokenização mostra onde cortar de forma limpa, em vez de deixar a API rejeitar tudo.

A ferramenta visual da consola

Para prototipagem, a xAI oferece um tokenizador visual na sua consola web, onde cola texto e vê imediatamente a sua desagregação. É uma excelente ferramenta de ensino — utilize-a pelo menos uma vez antes de desenhar os seus modelos de prompt.

Fará três observações úteis aí. O português gera significativamente mais tokens do que o inglês para conteúdos semanticamente idênticos, o que impacta diretamente o custo de uma aplicação em língua portuguesa. O código-fonte é dividido segundo uma lógica diferente da do texto natural. E a pontuação ou caracteres especiais ocupam frequentemente um token por si sós, o que explica por que razão JSON verboso custa surpreendentemente muito a transmitir.

Onde colocar a contagem num pipeline

Cuidado com o reflexo de tokenizar sistematicamente antes de cada chamada: duplica o número de pedidos de rede e adiciona latência a cada interação, para obter informação que muitas vezes já conhece. Reserve a contagem exata para casos em que a incerteza é real.

Para todo o resto, uma estimativa é suficiente. Conte aproximadamente 1,5 tokens por palavra em português, cerca de 0,3 tokens por carácter de código e entre 256 a 1.792 tokens por imagem, dependendo do seu tamanho. Estas ordens de grandeza, aplicadas no lado do cliente, permitem-lhe rejeitar localmente um prompt manifestamente fora dos limites sem consumir uma chamada.

Guarde o endpoint para três situações: prompts cujo tamanho varia amplamente, tipicamente documentos fornecidos pelo utilizador ou excertos recuperados por um sistema RAG; calibração inicial dos seus modelos, quando estabelece de uma vez por todas o orçamento de tokens para cada bloco de construção; e depuração, quando surge um erro de excedente de contexto e precisa de identificar qual o elemento que causou o inchaço.

Ferramentas integradas, uma rubrica separada

Os tokens não são a única fonte de custos. As ferramentas integradas da API são faturadas por chamada, independentemente do volume de texto trocado.

FerramentaTarifa
Web Search$5 por 1.000 chamadas
X Search$5 por 1.000 chamadas
Code Execution$5 por 1.000 chamadas
File Attachments$10 por 1.000 chamadas
Collections Search$2,50 por 1.000 chamadas

Faça as contas ao seu próprio tráfego antes de generalizar uma ferramenta. Uma aplicação que aciona uma pesquisa web em cada pedido paga $5 por mil interações apenas pela ferramenta, o que frequentemente excede o custo dos tokens consumidos no mesmo período. A pesquisa web não é supérflua, mas deve ser acionada sob condição e não por defeito.

Pontos-chave

  • O endpoint POST /v1/tokenize-text permite contar tokens sem faturação
  • A consola de tokenização web é útil para prototipagem e compreensão do tokenizador
  • Não chame o endpoint de tokenização em cada pedido em produção: utilize estimativas
  • As ferramentas integradas (Web Search, Code Execution, etc.) têm custos adicionais por chamada
  • O português consome em média cerca de 1,5 tokens por palavra