Respuesta breve
max_tokens limita el número de tokens que el modelo puede generar en una respuesta. Cada API y modelo puede usar nombres de campo, requisitos y comportamientos predeterminados diferentes.
Para obtener resultados estables, define un límite de salida explícito en respuestas largas, generación de código y tareas de documentación. En llamadas a API compatibles con Claude / Anthropic, normalmente debes enviar max_tokens de forma explícita.
Conceptos básicos
Si el límite de salida es demasiado bajo, la respuesta puede quedar cortada. Si es muy alto, el modelo no siempre generará todos esos tokens, pero las tareas con salidas largas pueden costar más.
Diferentes nombres de parámetros
Si usas Codex CLI u otra herramienta basada en la API Responses, utiliza el campo que admita actualmente esa herramienta o proveedor. No fijes el mismo nombre de parámetro para todos los modelos.
Qué ocurre si no lo configuras
El comportamiento depende del proveedor y de la API:
El mismo código puede producir salidas de distinta longitud al cambiar de modelo. Para evitar sorpresas en producción, define un límite de salida explícito.
Rangos recomendados
Consulta el máximo real en la model plaza y en la documentación del modelo original. Los límites de salida pueden cambiar según la versión.
Qué hacer si la salida queda cortada
Si la respuesta contienefinish_reason: "length", normalmente el modelo alcanzó el límite de salida.
Soluciona el problema en este orden:
- Aumenta el campo de límite de salida que admite la API actual.
- Comprueba que hayas usado el nombre de parámetro correcto.
- Acota el prompt para reducir la salida innecesaria.
- Usa un modelo con una ventana de salida mayor.
- Divide la tarea en varios pasos.
Errores habituales
- Suponer que un valor mayor de
max_tokenssiempre hace que el modelo escriba más. - Reintentar después de un corte sin comprobar
finish_reason. - Usar un nombre de campo antiguo con un modelo de razonamiento.
- Ignorar los tokens de razonamiento ocultos al estimar el contexto y el coste.
- Ignorar el límite máximo de salida del propio modelo.