“Unsupported parameter: 'max_tokens' is not supported with this model”

A renomeação é a parte fácil. O que costuma surpreender é o que o novo campo contabiliza — max_completion_tokens inclui raciocínio e saída visível; portanto, um orçamento dimensionado apenas para a resposta pode retornar vazio com finish_reason "length", e ainda ser cobrado.

O erro

response (HTTP 400)

{
  "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 e soluções em resumo

Causa	Solução
As famílias de modelos de raciocínio substituíram o campo	Envie max_completion_tokens em vez de max_tokens nesses modelos.
Um SDK ou wrapper fixado no campo antigo	Atualize-o ou defina o campo explicitamente, em vez de usar o helper.
Um caminho de código distribuindo chamadas para vários provedores	Normalize uma vez na borda, em vez de criar ramificações por modelo.
Resposta vazia depois da correção	O orçamento inclui tokens de raciocínio — aumente-o bastante acima da saída esperada.

Renomeie o campo

No ponto da chamada, é uma substituição direta. Todo o restante da solicitação permanece inalterado.

fix.py

# 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)

Reserve orçamento para o raciocínio que você não vê

max_completion_tokens limita conjuntamente os tokens de raciocínio e a saída visível. Se um modelo gastar 900 tokens pensando sob um limite de 1.024, você receberá 124 tokens de resposta — ou uma mensagem vazia com finish_reason "length", e será cobrado por tudo. Dimensione o orçamento para ambos e verifique finish_reason antes de considerar uma resposta vazia válida.

Normalize uma vez, em vez de criar ramificações por modelo

Um único helper na borda do código mantém o restante independente do provedor e impede que a próxima família de modelos exija outra rodada de alterações.

normalize.py

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))

Espere rejeições relacionadas

As mesmas famílias de modelos que abandonaram max_tokens geralmente também rejeitam temperature e top_p. Corrigir este campo costuma revelar o próximo problema; remova os parâmetros de amostragem incompatíveis em vez de defini-los com seus valores padrão.

Se você estiver chamando pela Kunavo

O /v1/chat/completions do Kunavo aceita max_tokens na família de raciocínio GPT-5.x: o tradutor lê qualquer uma das duas grafias enviadas e a mapeia para o campo upstream; o /v1/responses faz o inverso. Portanto, nesses modelos, você não precisa renomear nada. Uma assimetria que deve ser dita claramente: nos modelos claude-*, o tradutor de chat atualmente lê apenas max_tokens; portanto, envie essa grafia para o Claude — é isso que o helper acima faz.

Perguntas frequentes

max_completion_tokens é apenas uma renomeação?

No ponto da chamada, sim; em significado, não — ele limita conjuntamente os tokens de raciocínio e a saída, enquanto max_tokens limitava apenas a saída visível.

Por que minha resposta ficou vazia depois dessa correção?

O orçamento foi consumido pelo raciocínio. Verifique finish_reason: "length"; conteúdo vazio significa que você deve aumentar o limite.

Preciso criar uma ramificação por modelo?

No Kunavo, não para a família GPT — as duas grafias são aceitas. Crie uma ramificação apenas para modelos claude-* ou use um único helper de normalização em todos os lugares.

Guias relacionados

Mais detalhes sobre o significado dos erros estão em referência de erros; obter uma chave leva um minuto por meio de cadastro e da guia de autenticação.

“Unsupported parameter: 'max_tokens' is not supported with this model” — use max_completion_tokens