Endpoint de tokenização e ferramentas
Nesta página
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.
| Ferramenta | Tarifa |
|---|---|
| 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-textpermite 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