La rinomina è la parte semplice. Il punto che sorprende è cosa conta il nuovo campo: max_completion_tokens include ragionamento e output visibile, quindi un budget dimensionato solo per la risposta può restituire una risposta vuota con finish_reason "length", oltre a essere addebitato.
L’errore
{
"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"
}
}Cause e soluzioni in breve
| Causa | Soluzione |
|---|---|
| Le famiglie di modelli di ragionamento hanno sostituito il campo | Invia max_completion_tokens invece di max_tokens per questi modelli. |
| Un SDK o wrapper bloccato sul vecchio campo | Aggiornalo oppure imposta esplicitamente il campo invece di usare l'helper. |
| Un unico percorso di codice che distribuisce richieste su più provider | Normalizza una volta al bordo invece di creare rami per modello. |
| Risposta vuota dopo la correzione | Il budget include i token di ragionamento: aumentalo ben oltre l'output previsto. |
Rinomina il campo
Nel punto della chiamata è una sostituzione diretta. Tutto il resto della richiesta rimane invariato.
# 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)Prevedi un budget per il ragionamento invisibile
max_completion_tokens limita insieme i token di ragionamento e l'output visibile. Se un modello usa 900 token per ragionare con un limite di 1.024, ricevi 124 token di risposta — oppure un messaggio vuoto con finish_reason "length", con addebito per tutto. Dimensiona il budget per entrambi e controlla finish_reason prima di considerare affidabile una risposta vuota.
Normalizza una volta invece di creare rami per modello
Un singolo helper al bordo del codice mantiene il resto indipendente dal provider e impedisce che la prossima famiglia di modelli richieda un altro ciclo di modifiche.
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))Aspettati i rifiuti dei parametri correlati
Le stesse famiglie di modelli che hanno abbandonato max_tokens spesso rifiutano anche temperature e top_p. Risolvere questo problema ne fa spesso emergere un altro; rimuovi i parametri di campionamento non supportati invece di impostarli sui valori predefiniti.
Se chiami tramite Kunavo
L'endpoint /v1/chat/completions di Kunavo accetta max_tokens per la famiglia di ragionamento GPT-5.x: il traduttore legge una delle due forme che invii e la mappa sul campo upstream, mentre /v1/responses esegue la trasformazione inversa. Per questi modelli non devi quindi rinominare nulla. Un'asimmetria espressa chiaramente: sui modelli claude-* il traduttore chat attualmente legge solo max_tokens, quindi per Claude invia quella forma — è ciò che fa l'helper precedente.
Domande frequenti
max_completion_tokens è solo una rinomina?
Nel punto della chiamata sì, nel significato no: limita insieme i token di ragionamento e l'output, mentre max_tokens limitava solo l'output visibile.
Perché la risposta è vuota dopo questa correzione?
Il budget è stato consumato dal ragionamento. Controlla finish_reason: "length" con contenuto vuoto significa che devi aumentare il limite.
Devo creare un ramo per ogni modello?
Su Kunavo non per la famiglia GPT: entrambe le forme sono accettate. Crea un ramo solo per i modelli claude-* oppure usa ovunque un unico helper di normalizzazione.
Guide correlate
- context_length_exceeded / prompt troppo lungo — soluzioni che non rendono la tua app inutilizzabile
- API compatibile con OpenAI che restituisce 401/403 — errori comuni di base_url e degli header
- “Streaming interrupted. Waiting for the complete message” — significato e soluzione
Ulteriori dettagli sul significato degli errori sono disponibili in riferimento agli errori; ottenere una chiave richiede un minuto tramite registrazione e la guida all’autenticazione.