Qwen4-Max API 연결하기: 프리뷰에서 출시 모델로 전환하는 방법

Qwen4-Max 모델 ID, 지역, 결제 경로를 맞추고 출력 한도·도구 이력·첫 응답을 검증한 뒤 에이전트를 전환하세요.

접이식 다리가 작은 주황색 자동차의 안전한 이동 경로를 만드는 모습으로 검증된 전환을 표현합니다.

Qwen4-Max는 현재 공식 문서에서 qwen4-max라는 API ID를 사용하는 출시 모델로 안내됩니다. qwen4-max-preview와는 별개입니다. 예전 글에서 Qwen4를 프리뷰 구독으로만 사용할 수 있다고 설명한다면 애플리케이션 설정 전에 최신 공식 문서를 확인하세요.

이 가이드는 2026년 11월 16일 확인했습니다. QwenCloud 직접 API를 사용하며, 마이그레이션 시 결정할 사항과 간단한 응답 검증기를 제공합니다. 문서와 로컬 합성 응답 사례를 확인했으며, 이 글을 위해 유료 Qwen4 호출이나 모델 성능 측정을 하지는 않았습니다. 아래 예시는 직접 실행할 요청과 합격 기준이지 성능 실측 결과가 아닙니다.

무엇이 달라졌고 어떤 모델을 선택해야 할까

공식 모델 페이지는 이제 qwen4-max를 설명하며, 프리뷰 자료는 다른 ID를 가리킵니다. 호출할 경로에서 지원하는 정확한 이름을 사용하세요. 다른 게이트웨이의 제공업체 접두사를 붙이거나 클라이언트 표시 이름을 API ID라고 가정하면 안 됩니다.

출시 모델의 문서에는 텍스트 생성, 이미지·영상 이해, 도구 호출, 구조화된 출력이 명시되어 있습니다. 업무 자동화에서는 기능을 구분해야 합니다. 이미지 이해는 이미지 생성과 다르며, 모델이 슬라이드 내용을 반환한다고 편집 가능한 발표 파일이 만들어지는 것도 아닙니다. 파일 생성·실행·전달에는 해당 도구와 결과를 확인하는 실행 환경이 필요합니다.

결정 사항설정 변경 전 확인할 내용
출시 모델과 프리뷰이 가이드에서는 qwen4-max를 선택하고 프리뷰 설정은 별도 보관
직접 API와 게이트웨이해당 제공업체의 카탈로그, 인증 정보, 프로토콜 확인
종량제와 Token Plan선택한 결제 경로에 맞는 엔드포인트와 키 사용
지역콘솔 지역, 키, 엔드포인트를 일치시킴
에이전트 마이그레이션HTTP 성공뿐 아니라 완료한 작업과 결과물 검증

공식 컨텍스트 한도는 1,000,000토큰입니다. 출시 모델 문서의 최대 출력은 추론을 끄면 131,072토큰, 추론과 최종 답변을 합하면 262,144토큰입니다. 이는 상한이며 첫 요청에 권장하는 기본값이 아닙니다. 이전 프리뷰 출력 수치를 출시 모델 설정에 복사하지 마세요.

QwenCloud 계정을 직접 연결하기

종량제 연동에는 사용할 QwenCloud 지역에서 API 키를 만들거나 선택합니다. 공식 API 키 안내와 지역·엔드포인트 문서를 따르세요. 요청을 보내기 전에 계정 접근 권한과 결제 설정을 확인합니다.

아래 예시는 싱가포르 지역을 사용합니다.

Base URL: https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1
Model: qwen4-max
Protocol: OpenAI-compatible Chat Completions

Token Plan 키는 별도 경로를 사용합니다. 이 키를 종량제 예시에 붙여 넣지 말고 Token Plan 문서를 따르세요. 두 경로가 익숙한 프로토콜을 지원해도 이용 권한과 결제가 합쳐지는 것은 아닙니다.

키는 서버 측 환경 변수 DASHSCOPE_API_KEY에 보관하세요. 저장소에 커밋하거나 스크린샷에 노출하지 마세요. 값을 출력하지 않고 설정 여부만 확인하려면 다음 명령을 사용합니다.

python3 -c 'import os; print("Key configured:", bool(os.environ.get("DASHSCOPE_API_KEY")))'

이 명령은 값의 존재 여부만 확인합니다. 선택한 경로가 키를 받아들이는지는 인증된 요청의 성공 여부로 확인해야 합니다.

작은 첫 요청을 보내고 결과 확인하기

다음 내용을 request.json으로 저장합니다.

{
  "model": "qwen4-max",
  "messages": [
    {
      "role": "user",
      "content": "Return exactly three short checklist items for reviewing an API integration."
    }
  ],
  "enable_thinking": false,
  "max_completion_tokens": 1024
}

이 연결 확인에서는 추론을 명시적으로 껐습니다. 모든 코딩·조사 작업에 권장하는 설정이라는 뜻은 아닙니다. 각 제어 옵션은 추론 가이드를 참고하세요. 토큰 상한은 출력 토큰을 제한하지만 도구를 사용하는 긴 워크플로 전체 비용까지 제한하지는 않습니다.

사용할 유료 계정을 선택한 뒤에만 다음 명령을 실행하세요.

curl --silent --show-error --fail-with-body \
  --max-time 120 \
  https://ap-southeast-1.maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  -o response.json

타임아웃 뒤에 명령을 자동으로 반복하지 마세요. 응답이 터미널에 도착하지 않았어도 서버는 요청을 처리했을 수 있습니다. 먼저 제공업체의 요청 기록과 사용량을 확인하세요. 이 예시에는 의도적으로 자동 재시도 루프가 없습니다.

다음 코드를 check_response.py로 저장하고 python3 check_response.py response.json을 실행합니다.

import json
import sys
from pathlib import Path

payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
if payload.get("error"):
    raise SystemExit("API error: inspect response.json locally.")
choices = payload.get("choices") or []
if not choices:
    raise SystemExit("No choices returned; inspect the response format.")
choice = choices[0]
reason = choice.get("finish_reason")
message = choice.get("message") or {}
text = message.get("content")
if reason != "stop":
    raise SystemExit(f"Incomplete text check: finish_reason={reason!r}")
if not isinstance(text, str) or not text.strip():
    raise SystemExit("No usable final text returned.")
print(text)
print("Usage:", payload.get("usage", "not supplied"))

검증 통과는 비어 있지 않은 텍스트와 정상 종료 표시가 있다는 뜻입니다. 요청한 세 항목이 실제로 포함됐는지는 별도로 확인해야 합니다. 이 스크립트는 첫 텍스트 전용 요청에 맞췄습니다. 정상적인 도구 호출도 중간 결과이므로 최종 답변으로 통과시켜서는 안 됩니다.

재현을 위해 요청 날짜, 엔드포인트 지역, 반환된 모델 ID, 종료 이유, 사용량, 작업 결과를 기록하세요. 원본 응답에 사용자 데이터가 있다면 비공개로 보관합니다.

기존 코딩·업무 에이전트 마이그레이션하기

마이그레이션에서는 새 경로가 필요한 프로토콜을 실행하는지와 에이전트가 여전히 결과물을 전달하는지를 나눠 확인해야 합니다. 짧은 인사 응답만으로는 프로토콜 전체나 작업 품질을 확인할 수 없습니다.

  1. 현재 설정을 저장합니다. 제공업체, 모델, 엔드포인트, 클라이언트 버전, 도구 권한을 기록하세요. 모든 환경의 정상 설정을 한꺼번에 바꾸지 말고 되돌릴 수 있게 변경합니다.
  2. 격리된 작업부터 시작합니다. 작은 저장소나 합성 업무 문서를 사용하세요. 테스트가 통과하는 패치, 합계가 맞는 워크북, 출처를 확인할 수 있는 보고서처럼 예상 결과를 먼저 정의합니다.
  3. 클라이언트별 설정을 확인합니다. QwenCloud는 Qwen Code, Codex, Claude Code별 가이드를 제공합니다. 한 실행 환경의 설정은 범용 API 예제가 아닙니다.
  4. 도구 왕복 호출을 한 번 확인합니다. 안전한 테스트 파일을 살펴보고, 읽기 전용 도구를 호출하고, 결과를 받은 뒤 답변에 사용하게 합니다. 호출 ID와 이력이 왕복 과정에서 유지되는지 확인하세요.
  5. 실제 결과물을 검사합니다. 생성 파일을 열거나 패치를 검토하세요. 모델의 완료 선언과 별개로 수식, 인용, 테스트를 확인합니다.
  6. 범위를 점진적으로 늘립니다. 동일 입력으로 현재 설정과 성공한 작업 비용, 소요 시간, 사람의 개입을 비교하세요. 보기 좋은 답변 하나로 운영 워크플로를 교체하기에는 부족합니다.

합성 스프레드시트 작업에 재사용할 수 있는 검증 프롬프트입니다.

Use only the supplied sales.csv. Calculate revenue by month from quantity
and unit_price. Flag missing values rather than inventing them. Deliver:
1. the calculation method;
2. the totals with the source row IDs;
3. a list of excluded rows and reasons.
Do not claim to have created an Excel file unless you actually create and
attach one. Stop and report any tool or file-access failure.

이는 제안하는 테스트이며 Qwen4가 통과했다는 주장이 아닙니다. 합계를 독립적으로 다시 계산한 뒤 중복 행, 다른 통화 등 더 어려운 사례를 추가하세요.

결과를 조용히 망가뜨릴 수 있는 두 가지 변경점

출력 예산의 의미가 달라졌습니다. API 호환성 안내는 Qwen4 프리뷰 세대부터 max_tokens가 추론과 답변을 합친 예산을 제한한다고 설명합니다. 이전에는 표시할 답변 공간이 충분했던 설정도 추론을 켜면 다르게 동작할 수 있습니다. 상한부터 높이지 말고 완료 상태와 사용량을 확인하세요. 한 번에 하나씩 바꾸고 비용을 측정합니다.

도구 이력에는 눈에 보이는 답변 이상이 필요합니다. 함수 호출 문서와 추론 문서는 턴 사이에 어시스턴트 추론과 도구 결과를 전달하는 방법을 설명합니다. 일반 텍스트 대화록만으로 이력을 재구성하면서 프로토콜 필드를 버리지 마세요. 일반적인 연동 패턴은 Qwen 등 모델의 멀티턴 도구 호출 가이드를 참고하되, 예전 모델 예시가 Qwen4의 현재 규격을 대신하지는 않습니다.

재시도 전에 실패 원인부터 구분하기

증상먼저 확인할 것다음 조치
인증 거부키가 선택한 경로·지역에 속하는지키와 엔드포인트 조합 수정, 문의 글에 비밀값 출력 금지
모델 이용 불가 또는 찾을 수 없음정확한 ID, 계정 권한, 제공업체 카탈로그해당 경로가 qwen4-max를 지원하는지 확인하고 별칭을 추측하지 않음
요청 매개변수 거부다른 모델·프로토콜의 설정이 전송되는지위 최소 요청으로 줄인 뒤 필요한 필드를 하나씩 추가
잘리거나 비어 있는 최종 답변종료 이유, 추론 예산, 출력 상한예산 변경 전에 사용량과 원본 응답 확인
도구 루프 중단어시스턴트 호출, 대응 결과, 추론 이력직렬화한 메시지를 공식 멀티턴 예시와 비교
호출 제한계정 할당량, 동시 요청 수, 응답 안내동시성을 낮추고 재시도가 적절한 경우에만 제한된 백오프 적용
“완료”라고 하지만 파일이 없음도구 실행과 결과물 저장실제 파일을 요구하고 내용 확인 후 완료 처리

이는 진단 분기이며 Qwen4에서 모든 오류를 재현했다는 뜻은 아닙니다. 잘못된 ID와 미지원 엔드포인트를 구분하려면 model not found 문제 해결 가이드 (영문)를 참고하세요.

비용과 Ofox 지원 여부는 따로 확인하기

QwenCloud의 현재 가격 문서는 지역별로 입력, 출력, 캐시 작업을 구분합니다. 추론 토큰은 출력 과금에 포함됩니다. 프리뷰 크레딧 프로모션은 출시 모델의 보편적인 가격이 아니며 Token Plan 할당량도 종량제 단가와 다릅니다.

캐시를 쓰지 않는 비교에서는 입력 토큰에 해당 입력 단가를 곱하고 출력 토큰에 출력 단가를 곱해 더합니다. 두 단가의 토큰 단위를 먼저 맞추세요. 도구 루프의 모든 모델 호출을 합산해야 합니다. 캐시 작업은 제공업체의 과금 규칙대로 쓰기와 읽기를 분류해 같은 토큰을 중복 계산하지 마세요. 결과 옆에 지역과 가격 확인 날짜도 기록합니다.

11월 16일 Ofox 공개 카탈로그 스냅샷에는 Qwen4-Max가 없었습니다. 따라서 위 QwenCloud 직접 연결 설정은 Ofox 연동 방법이 아닙니다. 지금 사용할 Ofox 경로가 필요하다면 Qwen3.8 Max 0902 모델 페이지를 확인하고, Qwen4의 별칭이 아닌 다른 모델로 평가하세요.

Ofox 요청에는 Ofox API 키 인증과 Ofox 오류 처리를 따르세요. 해당 인증 정보와 규칙으로 QwenCloud 요청이 인증되는 것은 아닙니다. 설정을 게이트웨이로 옮기기 전에 새 모델의 실제 카탈로그 항목과 지원 프로토콜을 확인하세요.

자주 묻는 질문

Qwen4-Max는 아직 프리뷰 전용인가요?
아닙니다. 현재 공식 문서에는 qwen4-max의 종량제 및 Token Plan 접근이 안내되어 있습니다. qwen4-max-preview는 별도 ID이므로 프리뷰 조건을 출시 모델에 적용하지 마세요.
Ofox로 Qwen4-Max를 호출할 수 있나요?
2026년 11월 16일 확인한 공개 카탈로그에서는 Qwen4-Max를 찾지 못했습니다. 이 가이드는 QwenCloud 직접 연결을 사용하며 Ofox 지원을 주장하지 않습니다.
100만 토큰 컨텍스트이면 출력도 100만 토큰인가요?
아닙니다. 출시 모델의 컨텍스트는 1,000,000토큰이며 입력·출력 한도가 별도로 적용됩니다. 최대 출력은 추론 없이 131,072토큰, 추론과 답변을 합해 262,144토큰입니다.