El cambio de nombre es la parte fácil. Lo que suele sorprender es qué cuenta el nuevo campo: max_completion_tokens cubre el razonamiento más la salida visible, por lo que un presupuesto calculado solo para la respuesta puede devolverla vacía con finish_reason «length» y generar cargos.
El error
{
"error": {
"message": "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.",
"type": "invalid_request_error",
"param": "max_tokens",
"code": "unsupported_parameter"
}
}Causas y soluciones de un vistazo
| Causa | Solución |
|---|---|
| Las familias de modelos de razonamiento sustituyeron el campo | Envía max_completion_tokens en lugar de max_tokens en esos modelos. |
| Un SDK o wrapper fijado al campo antiguo | Actualízalo o establece el campo explícitamente en lugar de hacerlo mediante el helper. |
| Una ruta de código que distribuye solicitudes entre varios proveedores | Normaliza una sola vez en el borde en lugar de crear ramas por modelo. |
| Respuesta vacía después de corregirlo | El presupuesto incluye tokens de razonamiento: elévalo bastante por encima de la salida esperada. |
Cambia el nombre del campo
En el punto de llamada es una sustitución directa. Todo lo demás de la solicitud permanece sin cambios.
# Before
resp = client.chat.completions.create(
model="gpt-5-6-sol", max_tokens=1024, messages=msgs)
# After
resp = client.chat.completions.create(
model="gpt-5-6-sol", max_completion_tokens=1024, messages=msgs)Presupuesta el razonamiento que no puedes ver
max_completion_tokens limita conjuntamente los tokens de razonamiento y la salida visible. Si un modelo consume 900 tokens pensando con un límite de 1.024, obtienes 124 tokens de respuesta, o un mensaje vacío con finish_reason «length», y se te factura todo. Calcula el presupuesto para ambos y comprueba finish_reason antes de confiar en una respuesta vacía.
Normaliza una sola vez en lugar de crear ramas por modelo
Un único helper en el borde de tu código mantiene el resto independiente del proveedor y evita que la siguiente familia de modelos requiera otra ronda de ediciones.
def token_budget(model: str, n: int) -> dict:
"""One place that knows which spelling a model wants."""
if model.startswith("claude-"):
return {"max_tokens": n}
return {"max_completion_tokens": n}
resp = client.chat.completions.create(
model=model, messages=msgs, **token_budget(model, 4096))Espera rechazos relacionados
Las mismas familias de modelos que eliminaron max_tokens suelen rechazar también temperature y top_p. Corregir este parámetro suele revelar el siguiente; elimina los parámetros de muestreo no compatibles en lugar de establecerlos con sus valores predeterminados.
Si llamas a través de Kunavo
El endpoint /v1/chat/completions de Kunavo acepta max_tokens en la familia de razonamiento GPT-5.x: el traductor lee cualquiera de las dos variantes que envíes y la asigna al campo ascendente, y /v1/responses hace lo mismo a la inversa. Por tanto, en esos modelos no tienes que cambiar el nombre. Una asimetría expresada claramente: en los modelos claude-* el traductor de chat actualmente solo lee max_tokens, así que envía esa variante para Claude, que es lo que hace el helper anterior.
Preguntas frecuentes
¿max_completion_tokens es solo un cambio de nombre?
En el punto de llamada, sí; en significado, no: limita conjuntamente los tokens de razonamiento y la salida, mientras que max_tokens limitaba solo la salida visible.
¿Por qué mi respuesta está vacía después de corregirlo?
El presupuesto se gastó en razonamiento. Comprueba finish_reason: «length» con contenido vacío significa que debes elevar el límite.
¿Tengo que crear ramas por modelo?
En Kunavo, no para la familia GPT: se aceptan ambas variantes. Crea ramas solo para los modelos claude-* o utiliza un único helper de normalización en todas partes.
Guías relacionadas
- context_length_exceeded / la indicación es demasiado larga: soluciones que no dejan tu aplicación incapacitada
- API compatible con OpenAI que devuelve 401/403: errores habituales de base_url y headers
- «Streaming interrumpido. Esperando el mensaje completo»: qué significa y cómo solucionarlo
Encontrarás más detalles sobre el significado de los errores en referencia de errores; obtener una clave lleva un minuto mediante registro y la guía de autenticación.