Resposta curta
max_tokens limita quantos tokens o modelo pode gerar em uma resposta. APIs e modelos diferentes usam nomes de campos, requisitos e comportamentos padrão distintos.
Para obter uma saída estável, defina um limite explícito em respostas longas, geração de código e tarefas de documentação. Em chamadas Claude / compatíveis com Anthropic, geralmente é necessário enviar max_tokens explicitamente.
Conceitos principais
Se o limite for pequeno demais, a resposta poderá ser cortada. Se for muito grande, o modelo não gerará necessariamente todos esses tokens, mas tarefas com saídas longas podem custar mais.
Nomes de parâmetros diferentes
Se você usa o Codex CLI ou outra ferramenta baseada na Responses API, use o campo aceito pela ferramenta ou pelo provedor. Não fixe o mesmo nome de parâmetro para todos os modelos.
O que acontece se você não definir o limite
O comportamento varia conforme o provedor e a API:
O mesmo código pode produzir respostas de tamanhos diferentes após a troca de modelo. Para evitar surpresas em produção, defina um limite explícito.
Faixas recomendadas
Consulte o limite real na model plaza e na documentação upstream. Os limites de saída podem mudar entre versões.
O que fazer quando a saída é cortada
Se a resposta contiverfinish_reason: "length", o modelo provavelmente atingiu o limite de saída.
Verifique nesta ordem:
- Aumente o campo de limite aceito pela API atual.
- Confirme que usou o nome de parâmetro correto.
- Torne o prompt mais específico para reduzir conteúdo desnecessário.
- Use um modelo com uma janela de saída maior.
- Divida a tarefa em várias etapas.
Erros comuns
- Achar que um valor maior de
max_tokenssempre faz o modelo escrever mais. - Tentar novamente após um corte sem conferir
finish_reason. - Usar um nome de campo antigo com um modelo de raciocínio.
- Ignorar tokens ocultos de raciocínio ao estimar contexto e custo.
- Ignorar o limite máximo de saída do próprio modelo.