“Unsupported parameter: 'max_tokens' is not supported with this model” — max_completion_tokens를 사용하세요

이름 변경은 쉬운 부분입니다. 사람들이 놓치는 부분은 새 필드가 계산하는 대상입니다 — max_completion_tokens는 추론과 표시되는 출력을 모두 포함하므로 답변만 기준으로 예산을 설정하면 finish_reason이 "length"가 되고 빈 응답이 반환되며 비용은 청구됩니다.

오류

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"
  }
}

원인과 해결 방법 한눈에 보기

원인	해결 방법
추론 모델 제품군에서 필드가 변경됨	해당 모델에서는 max_tokens 대신 max_completion_tokens를 보내세요.
이전 필드에 고정된 SDK 또는 래퍼	업그레이드하거나 헬퍼를 거치지 말고 필드를 명시적으로 설정하세요.
여러 공급업체로 분기되는 하나의 코드 경로	모델별로 분기하지 말고 경계에서 한 번 정규화하세요.
수정 후 빈 답변	예산에 추론 토큰이 포함됩니다 — 예상 출력보다 훨씬 크게 설정하세요.

필드 이름을 변경하세요

호출 지점에서는 단순 치환입니다. 요청의 나머지 부분은 그대로입니다.

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)

보이지 않는 추론을 위한 예산을 잡으세요

max_completion_tokens는 추론 토큰과 표시되는 출력을 함께 제한합니다. 모델이 1,024 한도에서 900토큰을 생각하는 데 사용하면 답변은 124토큰만 남거나 finish_reason이 "length"인 빈 메시지가 반환되며 모두 비용이 청구됩니다. 둘 모두를 고려해 예산을 설정하고, 빈 응답을 신뢰하기 전에 finish_reason을 확인하세요.

모델별 분기 대신 한 번 정규화하세요

코드 경계에 하나의 헬퍼를 두면 나머지는 공급업체에 종속되지 않으며, 다음 모델 제품군이 추가될 때 또다시 코드를 수정할 필요가 없습니다.

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

같은 계열의 거부도 예상하세요

max_tokens를 제거한 동일한 모델 제품군은 temperature와 top_p도 거부하는 경우가 많습니다. 이 문제를 고치면 다음 문제가 드러나는 경우가 많으므로 지원되지 않는 샘플링 매개변수는 기본값으로 설정하지 말고 제거하세요.

Kunavo를 통해 호출하는 경우

Kunavo의 /v1/chat/completions는 GPT-5.x 추론 제품군에서 max_tokens를 허용합니다. 번역기가 두 표기 중 어느 것을 보내든 읽어 업스트림 필드로 매핑하며, /v1/responses도 반대 방향으로 동일하게 처리합니다. 따라서 해당 모델에서는 이름을 바꿀 필요가 없습니다. 한 가지 비대칭은 분명히 말하겠습니다. claude-* 모델에서는 채팅 번역기가 현재 max_tokens만 읽으므로 Claude에는 해당 표기를 보내야 하며, 위 헬퍼가 그렇게 처리합니다.

자주 묻는 질문

max_completion_tokens는 단순한 이름 변경인가요?

호출 지점에서는 그렇지만 의미는 다릅니다 — max_completion_tokens는 추론 토큰과 출력을 함께 제한하며, max_tokens는 표시되는 출력만 제한했습니다.

이 문제를 수정한 후 응답이 빈 이유는 무엇인가요?

예산이 추론에 사용된 것입니다. 빈 콘텐츠와 함께 finish_reason: "length"가 표시되면 한도를 올리세요.

모델별로 분기해야 하나요?

GPT 제품군에서는 Kunavo에서 그럴 필요가 없습니다 — 두 표기를 모두 허용합니다. claude-* 모델에서만 분기하거나 어디서나 하나의 정규화 헬퍼를 사용하세요.