Fundamentos de API e Token Explicados

Você já deve ter notado que muitos usuários experientes falam sobre API, Token, Temperature e outros termos que soam técnicos e confusos. Este capítulo explica esses conceitos centrais em linguagem simples. Entendê-los vai te ajudar a compreender como a IA realmente funciona e a usá-la de forma mais eficaz.

O que é API?

API em Português Claro

API = Interface de Programação de Aplicações

Essa definição parece técnica, então vamos colocar de outra forma.

Pense na IA como um restaurante:

• Versão web = Você come no restaurante
  • Decoração bonita (interface web)
  • Garçons (botões, campos de entrada)
  • Você pede, o chef cozinha, o garçom serve
• API = Você pede delivery
  • Sem decoração, você fala direto com a cozinha
  • Sem garçom, você fala direto com o chef
  • Você diz o que quer, o chef prepara e entrega

Diferença principal:

• Versão web: tem interface, conveniente para humanos
• API: não tem interface, conveniente para programas

Por que usar API?

Se a versão web é tão conveniente, por que se preocupar com API?

Motivo 1: Automação

Suponha que você precise que a IA processe 1.000 documentos e escreva 1.000 resumos:

• Versão web: Você copia e cola 1.000 vezes e clica em enviar 1.000 vezes
• API: Escreva um script que processa tudo automaticamente enquanto você toma um café

Motivo 2: Integração em seus próprios aplicativos

Você quer criar um bot de resposta automática, um gerador de conteúdo ou um agente de atendimento inteligente:

• Versão web: Não é possível
• API: Você pode incorporar a IA diretamente em seus próprios programas

Motivo 3: Custo mais baixo

• Assinatura web: ChatGPT Plus $20/mês, Claude Pro $20/mês
• API pagamento por uso: Pague apenas pelo que usar; uso leve pode custar apenas alguns dólares por mês

Motivo 4: Mais flexibilidade

• Ajustar parâmetros da IA (Temperature, comprimento máximo, etc.)
• Processamento em lote
• Formatos de entrada/saída personalizados

Como é uma chamada de API?

Aqui está um exemplo simples (não se preocupe se parecer estranho – vamos abordar em detalhes depois):

# Call the latest GPT-5.2 API with Python
response = openai.chat.completions.create(
    model="gpt-5.2",
    messages=[
        {"role": "user", "content": "Hello，Introduce yourself"}
    ]
)
print(response.choices[0].message.content)

Apenas algumas linhas de código, e a IA responde à sua pergunta – sem necessidade de navegador.

Identificadores oficiais de modelo de API em 30/01/2026:

• OpenAI: gpt-5.2, gpt-5.2-chat-latest, gpt-5.2-pro
• Anthropic Claude: claude-opus-4-5, claude-sonnet-4-5
• Google Gemini: gemini-3-pro-preview, gemini-3-flash-preview

Comparação Versão Web vs API

O que é Token?

O Conceito de Token

Token = A menor unidade de texto que a IA entende

Diferente dos humanos, que leem palavras e frases diretamente, a IA precisa dividir o texto em pequenos pedaços. Cada pedaço é chamado de token.

Exemplos:

Chinês:

• “你好” ≈ 1–2 tokens
• “今天天气不错” ≈ 4–8 tokens, dependendo do modelo

Inglês:

• “Hello” = 1 token
• “How are you today?” ≈ 5 tokens

Regras práticas simples:

• Inglês: 1 palavra ≈ 1 token (cerca de 4 caracteres)
• Chinês: 1 caractere ≈ 0,5–2 tokens (depende do modelo de IA)
• Números, pontuação: geralmente 1 símbolo = 1 token

Descoberta Importante: Diferentes Modelos de IA Definem Tokens de Forma Diferente!

Aqui está um segredo pouco conhecido: O mesmo texto pode ter uma contagem de tokens completamente diferente em diferentes modelos de IA!

Por quê? Porque cada empresa de IA tem seu próprio tokenizador, e eles dividem o texto de maneiras diferentes.

Exemplo real:

A mesma frase: “AI is revolutionizing market research.”

• GPT-3: 11 tokens
• GPT-3.5 e GPT-4: 9 tokens
• GPT-4o e GPT-5.2: 8 tokens

Viu? A mesma frase difere em 3 tokens entre modelos!

Outro exemplo em chinês:

A frase “人工智能正在改变世界” (“Inteligência artificial está mudando o mundo”):

• GPT-4o: talvez 10 tokens
• Claude Sonnet 4.5: talvez 12 tokens
• Gemini 3: talvez 8 tokens

Por que a diferença?

Cada empresa usa um método de tokenização diferente ao treinar seus modelos:

• OpenAI (série GPT): usa BPE (Byte-Pair Encoding)
• Anthropic (Claude): usa seu próprio tokenizador otimizado
• Google (Gemini): a documentação do Gemini diz “1 token ≈ 4 caracteres”
• DeepSeek: um tokenizador otimizado para chinês

Como isso te afeta?

1. Comparações de custo não são diretas

Suponha que você tenha 1.000 caracteres chineses:

• Com GPT-5.2 pode ser 1.500 tokens
• Com Claude Sonnet 4.5 pode ser 1.600 tokens
• Com Gemini 3 pode ser 1.400 tokens

Mesmo que cada um diga “entrada $X/1M tokens”, o custo real pode diferir em 10–20%!

2. Você não pode usar o mesmo calculador de tokens para todos os modelos

• O tokenizador oficial da OpenAI (https://platform.openai.com/tokenizer) funciona apenas para a série GPT
• Tokens do Claude precisam do método de cálculo da Anthropic
• Tokens do Gemini precisam do método de cálculo do Google

3. Idiomas não-ingleses mostram diferenças ainda maiores

Para chinês, japonês, árabe e outros idiomas não-ingleses, a eficiência de tokens pode variar em 30–40%. A maioria dos modelos de IA é treinada principalmente em inglês, então seus tokenizadores são melhor otimizados para inglês.

Por que o Token é Importante

1. Token determina o custo

O preço da API é baseado em tokens, não em contagem de caracteres.

Exemplo (preços oficiais em 30/01/2026):

• GPT-5.2: entrada $1,75/1M tokens, saída $14/1M tokens
• Claude Opus 4.5: entrada $5/1M tokens, saída $25/1M tokens
• Gemini 3 Flash: entrada $0,50/1M tokens, saída $3/1M tokens (nível padrão)

Você envia 500 tokens e a IA responde com 1.000 tokens:

• Com GPT-5.2: (500 × 1,75 + 1000 × 14) / 1.000.000 = $0,01488 (cerca de 1,5 centavos de dólar)
• Com Gemini 3 Flash: (500 × 0,50 + 1000 × 3) / 1.000.000 = $0,00325 (cerca de 0,3 centavos de dólar)

2. Token determina o comprimento do contexto

Todo modelo de IA tem um limite de tokens:

• GPT-5.2 (API): até 400.000 tokens
• GPT-5.2-chat-latest: até 128.000 tokens
• Claude Sonnet 4.5: até 200.000 tokens
• Gemini 3 Pro Preview: até 1.048.576 tokens (cerca de 1M)

Este limite inclui: seu prompt + resposta da IA + histórico da conversa.

O que acontece se você exceder o limite?

• A IA “esquece” as partes mais antigas da conversa
• Ou retorna um erro e não continua

Como Contar Tokens

Método 1: Estimar (rápido, mas não preciso)

• Chinês: número de caracteres × 1,5
• Inglês: número de palavras × 1,3

Método 2: Usar a ferramenta online correspondente

• OpenAI (série GPT): https://platform.openai.com/tokenizer
• Contador de tokens geral: https://token-counter.app (suporta vários modelos para comparação)
• Gemini: use o método count_tokens no Google AI Studio

Lembrete importante: Ao estimar entre modelos, sempre use a ferramenta específica para aquele modelo. Não use a contagem de tokens do GPT para estimar o custo do Claude!

Tokens de Entrada, Tokens de Saída, Tokens em Cache

A cobrança da API divide os tokens em três tipos:

1. Tokens de Entrada

• O conteúdo que você envia para a IA
• Inclui seu prompt, documentos enviados
• Relativamente baratos

2. Tokens de Saída

• O conteúdo que a IA retorna para você
• Inclui a resposta da IA
• Geralmente 2–10 vezes mais caros que os tokens de entrada

Por que a saída é mais cara? Porque a IA “pensa” (gera texto) usando mais recursos computacionais do que “lê” (processa entrada).

Exemplo (GPT-5.2):

• Entrada: $1,75/1M tokens
• Saída: $14/1M tokens (8× o preço da entrada!)

3. Tokens em Cache

Este é um truque para economizar custos!

Se você usa repetidamente o mesmo prompt, a IA pode armazená-lo em cache e evitar processá-lo novamente na próxima vez.

Exemplo: Você tem um prompt de 1.000 tokens e faz 10 perguntas:

• Sem cache: cada vez processa 1.000 tokens → total 10.000 tokens
• Com cache: primeira vez 1.000 tokens (preço normal), próximas 9 vezes 1.000 tokens (preço de cache, 90% mais barato)

Modelos que suportam cache:

• Anthropic Claude (Prompt Caching)
• OpenAI GPT-5.2 (suporta cache, 90% de desconto)

Regras de cobrança do cache:

• Primeira leitura: preço normal
• Acerto de cache: preço reduzido em 50–90%
• Validade do cache: geralmente 5–10 minutos

O que é Temperature?

O Conceito de Temperature

Temperature = Controla a “aleatoriedade” ou “criatividade” das respostas da IA

Lembre-se de que a IA essencialmente “calcula probabilidades”. Quando você pergunta “Qual é a cor do céu?”, a IA vê:

• “Azul” probabilidade 80%
• “Cinza” probabilidade 10%
• “Vermelho” probabilidade 5%

Temperature ajusta como a IA escolhe entre essas opções.

Valores de Temperature

Temperature geralmente varia de 0 a 2 (ou 0 a 1, dependendo da plataforma):

Temperature = 0 (mais conservador)

• A IA sempre escolhe a resposta de maior probabilidade
• Respostas muito estáveis e previsíveis
• Mesma pergunta → resposta quase idêntica toda vez
• Melhor para: perguntas factuais, geração de código, análise de dados

Temperature = 1 (equilibrado)

• A IA escolhe aleatoriamente de acordo com as probabilidades
• As respostas variam um pouco, mas permanecem razoáveis
• Padrão para a maioria das plataformas
• Melhor para: conversas cotidianas, uso geral

Temperature = 2 (mais agressivo)

• A IA tenta muitas possibilidades
• Respostas muito diversas e criativas
• Pode ser impreciso ou até sem sentido
• Melhor para: escrita criativa, brainstorming, trabalho artístico

Um Exemplo Prático

Pergunta: Dê um nome para minha cafeteria

Temperature = 0:

• “Café Starbucks” (mais comum, resposta mais segura)
• Quase o mesmo toda vez

Temperature = 1:

• “Café Luz da Manhã”
• “Hora do Aroma”
• “Grão & Aconchego”
• Varia, mas todos razoáveis

Temperature = 2:

• “Dimensão Quântica do Café”
• “Laboratório de Espuma Espaço-Tempo”
• “Terminal Cósmico de Latte”
• Muito criativo, mas possivelmente estranho demais

Quando Ajustar a Temperature

Temperature mais baixa (0–0,5):

• Escrever código, depurar
• Análise de dados, problemas de matemática
• Tradução, sumarização
• Qualquer tarefa que precise de precisão

Temperature mais alta (1,5–2):

• Escrever romances, poesia
• Dar nomes, criar slogans
• Brainstorming
• Qualquer tarefa que precise de criatividade

Diferentes modelos listam suas temperatures recomendadas em seus sites oficiais. Por exemplo, o site da DeepSeek mostra:

Você pode ajustar na versão web?

• A maioria das versões web não permite ajuste direto
• Mas a API oferece controle preciso

Comprimento do Contexto

O que é Comprimento do Contexto?

Comprimento do Contexto = Quanto conteúdo a IA consegue “lembrar” de uma vez

Diferente dos humanos, a IA não tem memória de longo prazo. Em cada conversa, a IA só consegue lembrar de uma quantidade limitada de conteúdo. Esse limite é chamado de comprimento do contexto, medido em tokens.

Por que a IA “Esquece”?

Você já deve ter passado por isso:

• Você conversa com a IA por muito tempo
• De repente a IA não lembra o que foi dito no início
• Parece que teve amnésia

Motivo: Você excedeu o limite de comprimento do contexto.

Exemplo:

• Comprimento do contexto do GPT-5.2 = 128.000 tokens
• Você e a IA têm 50 rodadas de conversa, usando 130.000 tokens no total
• Além do limite, a IA “esquece” as partes mais antigas

Impacto Prático do Comprimento do Contexto

1. Afeta a duração da conversa

• Contexto curto: apenas algumas dezenas de rodadas
• Contexto longo: centenas de rodadas

2. Afeta o processamento de documentos

• Contexto curto: apenas documentos curtos
• Contexto longo: livros inteiros

3. Afeta o custo

• Contexto mais longo → processamento mais lento
• Mais tokens → custo mais alto

Como Lidar com os Limites de Contexto

Método 1: Limpar a conversa regularmente

• Salvar informações importantes
• Iniciar uma nova conversa
• Recontar o contexto para a IA

Método 2: Resumir o histórico da conversa

• Pedir à IA para resumir o conteúdo anterior
• Usar esse resumo como início de uma nova conversa
• Economiza tokens

Método 3: Escolher um modelo com contexto grande

• Para documentos longos: use Gemini 3 Pro
• Para conversas longas: use Claude Sonnet 4.5

Outros Conceitos Importantes

Max Tokens

Max Tokens = Limita o comprimento máximo de uma única resposta da IA

• Definir Max Tokens = 100: a IA responde com no máximo 100 tokens
• Definir Max Tokens = 2000: a IA responde com no máximo 2000 tokens

Por que limitar?

• Controlar custo (tokens de saída são mais caros)
• Evitar respostas excessivamente longas
• Alguns cenários precisam apenas de respostas curtas

Top P (Nucleus Sampling)

Top P = Outra forma de controlar a aleatoriedade

Semelhante à Temperature, mas funciona de forma diferente:

• Top P = 0,1: considera apenas os 10% superiores das opções mais prováveis
• Top P = 0,9: considera os 90% superiores das opções mais prováveis

Geralmente:

• Ajuste apenas Temperature ou Top P – um é suficiente
• Na maioria dos casos, Temperature é mais intuitivo

Frequency Penalty e Presence Penalty

Usados para reduzir repetição

• Frequency Penalty: penaliza palavras usadas com frequência, reduzindo a repetição da mesma palavra
• Presence Penalty: penaliza palavras que já apareceram, incentivando a IA a introduzir novos tópicos

Faixa: -2,0 a 2,0

• Valores positivos: reduzem repetição
• Valores negativos: permitem mais repetição
• 0: sem intervenção

Resumo: Como Usar Esses Conceitos?

Uso Diário (Versão Web)

Se você usa apenas a versão web, não precisa se preocupar com esses parâmetros – os padrões funcionam bem.

Mas entender esses conceitos te ajuda a:

• Entender por que a IA às vezes “esquece” partes anteriores da conversa (limite de contexto)
• Entender por que usuários de API podem fazer coisas que você não pode (controle de parâmetros)
• Se preparar para usar a API no futuro

Ao Usar a API

Se você decidir usar a API, esses parâmetros se tornam muito importantes:

Configurações básicas (toda vez):

• model: escolha o modelo (ex.: gpt-5.2, claude-sonnet-4-5)
• max_tokens: limite o comprimento da resposta

Ajuste conforme sua necessidade:

• temperature: 0–0,5 para tarefas factuais, 1–2 para tarefas criativas
• top_p: geralmente funciona bem no padrão
• frequency_penalty: se a IA repete muito, defina para 0,5–1

Otimização de custo:

• Use cache para economizar dinheiro
• Controle max_tokens para evitar desperdício
• Escolha o modelo certo (você nem sempre precisa do mais caro)
• Lembre-se de que diferentes modelos definem tokens de forma diferente