Qwen 3.8 API 사용법

알리바바는 2026년 8월 초 Qwen 3.8-Max를 출시했으며, 이 API는 이미 Model Studio에서 사용 가능합니다. 이 모델은 총 2.4조 개의 매개변수(활성 950억 개), 1백만 토큰 컨텍스트 창, 그리고 백만 토큰당 $2 입력 / $6 출력이라는 균일한 가격을 제공합니다. 모델 자체에 대한 자세한 배경 지식을 원하시면, 저희 Qwen 3.8 설명서부터 시작하세요. 이 가이드는 실용적인 측면, 즉 키를 얻는 방법, 지역 선택, 첫 번째 호출 수행, 그리고 모델을 도구에 연결하는 방법을 다룹니다.

한 가지 세부 사항이 이 API를 대부분의 모델 출시와 차별화합니다. Qwen 3.8은 출시 첫날부터 두 가지 프로토콜을 지원합니다: OpenAI 호환 엔드포인트와 Anthropic 호환 엔드포인트. 기존 OpenAI SDK 코드가 작동합니다. Claude Code 설정도 세 가지 환경 변수로 작동합니다. 이러한 이중 프로토콜 설계 덕분에 Apidog에서 이 API를 다루는 것이 재미있습니다. Apidog에서는 동일한 프롬프트를 두 가지 프로토콜 형태에 모두 적용하고 각각의 스트리밍 방식을 확인할 수 있습니다. 자세한 내용은 아래에서 설명합니다.

버튼

여기 전체 설명이 있습니다.

시작하기 전에 필요한 것

아래 내용에 놀라지 않도록 빠른 참조입니다:

항목	값
모델 ID	`qwen3.8-max`
컨텍스트 창	1,000,000 토큰
최대 출력	65,536 토큰
입력 유형	텍스트 및 이미지
가격	1백만 토큰당 $2 입력 / $6 출력 (전체 컨텍스트에 걸쳐 균일)
추론 제어	`reasoning_effort`: xhigh (기본), medium, low
프로토콜	OpenAI 채팅 완료 + 응답, Anthropic 메시지
키 환경 변수	`DASHSCOPE_API_KEY`

이 모든 정보는 공식 Qwen 3.8 출시 게시물과 알리바바 클라우드 모델 스튜디오 문서에서 가져온 것입니다. 가중치에 대한 한 가지 참고 사항: 알리바바는 다음 주에 Hugging Face와 ModelScope에 오픈 가중치를 제공하겠다고 약속했지만, 2026년 8월 초 현재까지는 다운로드할 수 없습니다. 이 가이드의 모든 내용은 호스팅된 API를 기반으로 합니다.

1단계: QwenCloud에서 API 키 받기

home.qwencloud.com으로 이동하여 로그인하거나 계정을 생성하세요. 콘솔에 접속한 후 API 키를 생성하세요. 알리바바 플랫폼은 내부적으로 여전히 DashScope 이름을 사용하므로, 환경 변수 규칙은 DASHSCOPE_API_KEY입니다:

export DASHSCOPE_API_KEY="sk-your-key-here"

소스 코드에 넣지 말고 셸 프로필이나 .env 파일에 넣으세요. 이 가이드의 모든 코드 스니펫은 해당 변수에서 키를 읽어옵니다.

실제 비용을 지불하기 전에 모델을 테스트하고 싶다면, 싱가포르 지역에서만 유효하며 90일 동안 사용 가능한 1백만 토큰의 무료 할당량이 있습니다. 이는 진지한 평가 실행에 충분합니다.

2단계: 지역별 기본 URL 선택

모델 스튜디오는 세 가지 지역에서 OpenAI 호환 API를 제공합니다. 서버와 가장 가까운 곳을 선택하세요:

지역	기본 URL
베이징	`https://dashscope.aliyuncs.com/compatible-mode/v1`
싱가포르	`https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
미국 (버지니아)	`https://dashscope-us.aliyuncs.com/compatible-mode/v1`

싱가포르 엔드포인트(dashscope-intl)는 대부분의 국제 사용자에게 기본 선택 사항이며, 무료 할당량이 있는 곳입니다. 모델 스튜디오 모델 목록에 따르면, qwen3.8-max는 텍스트 생성뿐만 아니라 이미지 및 비디오 이해에도 사용 가능하며, 8월 3일 업데이트 기준으로 추천 모델 테이블 상단에 위치하고 있습니다.

아래 예시들은 싱가포르를 사용합니다. 베이징이나 버지니아에 더 가깝다면 기본 URL을 변경하세요.

3단계: 첫 번째 호출하기

이 엔드포인트는 OpenAI 채팅 완료 형식을 사용하므로, 공식 openai Python SDK가 그대로 작동합니다. DashScope 기본 URL을 가리키세요:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "system", "content": "You are a precise technical assistant."},
        {"role": "user", "content": "Explain idempotency in REST APIs in two sentences."},
    ],
)

print(completion.choices[0].message.content)

cURL에서 동일한 호출:

curl https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-max",
    "messages": [
      {"role": "user", "content": "Explain idempotency in REST APIs in two sentences."}
    ]
  }'

이전에 OpenAI 호환 제공업체를 사용해 본 적이 있다면, 여기에 새로운 것은 없을 것입니다. 그것이 핵심입니다. 다른 모델에서 마이그레이션하는 것은 기본 URL과 모델 ID를 변경하는 것입니다. 이전 세대에서 넘어오셨다면, 워크플로는 저희 Qwen 3.7 Plus API 가이드와 동일하며, 단지 새로운 모델 ID와 더 나은 성능을 가지고 있을 뿐입니다.

4단계: 응답 스트리밍 및 추론 읽기

Qwen 3.8-Max는 추론 모델이며, 기본적으로 사고합니다. 스트리밍 모드에서는 최종 답변이 일반 content 델타로 도착하기 전에 사고 과정이 reasoning_content 델타로 도착합니다. 둘 다 처리하세요:

stream = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[
        {"role": "user", "content": "Design a rate limiting strategy for a public API."}
    ],
    stream=True,
)

thinking_done = False
for chunk in stream:
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        print(reasoning, end="", flush=True)
    elif delta.content:
        if not thinking_done:
            print("\n--- answer ---")
            thinking_done = True
        print(delta.content, end="", flush=True)

사고 스트림에 대해 알아야 할 두 가지가 있습니다. 첫째, 사고 토큰은 다른 모든 것과 동일한 요율로 출력 토큰으로 청구되므로, 긴 추론 체인은 청구서에 반영됩니다. 둘째, 기본 노력 수준에서 모델은 열심히 추론하며, 이는 정확성에는 좋지만 채팅 UI에서는 느릴 수 있습니다. 이제 제어 방법에 대해 알아보겠습니다.

5단계: reasoning_effort 및 사고 플래그 조정

API는 reasoning_effort의 세 가지 공식 수준을 제공합니다: xhigh (기본), medium, low. 더 높은 노력은 더 많은 사고 토큰, 어려운 문제에 대한 더 나은 결과, 그리고 더 높은 지연 시간과 비용을 의미합니다. 더 낮은 노력은 분류, 추출 및 간단한 채팅에 적합합니다.

두 가지 관련 플래그가 사고 동작 자체를 제어합니다: enable_thinking은 추론 프로세스를 켜거나 끄고, preserve_thinking (기본적으로 켜짐)은 회전 간에 추론 컨텍스트를 유지합니다. OpenAI SDK를 사용할 때 extra_body를 통해 전달하세요. 이는 DashScope 확장 기능이기 때문입니다:

completion = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "Classify this ticket: 'Login page 500s on Safari.'"}],
    extra_body={
        "reasoning_effort": "low",
        "enable_thinking": True,
    },
)

사고 기능이 켜져 있든 꺼져 있든 토큰당 요금은 동일합니다. 비용을 변경하는 요소는 모델이 생성하는 사고 토큰의 수이며, 이는 reasoning_effort가 직접 제어합니다. 합리적인 기본값: 에이전트 코딩 및 분석에는 xhigh, 대용량 프로덕션 엔드포인트에는 low, 확실하지 않을 때는 medium. 알리바바의 기본값을 포함하여 다른 사람의 기본값을 신뢰하기보다는 자신의 워크로드를 벤치마킹하세요.

Anthropic 호환 엔드포인트

이 부분이 특이합니다. OpenAI 호환 API와 함께 Qwen 3.8은 Anthropic 프로토콜 엔드포인트를 제공합니다:

https://dashscope-intl.aliyuncs.com/apps/anthropic

이 엔드포인트는 Anthropic Messages 형식을 사용합니다. 이는 Claude의 API를 위해 구축된 모든 도구가 코드 변경 없이 Qwen 3.8-Max와 통신할 수 있음을 의미합니다. 주요 사용 사례는 Claude Code입니다. 알리바바는 공식 구성을 발표했으며, 세 가지 환경 변수는 다음과 같습니다:

export ANTHROPIC_BASE_URL=https://dashscope-intl.aliyuncs.com/apps/anthropic
export ANTHROPIC_AUTH_TOKEN=$DASHSCOPE_API_KEY
export ANTHROPIC_MODEL=qwen3.8-max

위 변수들을 설정한 후 claude를 실행하면, Claude Code는 Qwen 3.8-Max에 대해 완전한 에이전트 루프를 실행합니다. 여기서 잠시 주목할 만한 세부 사항이 있습니다: 알리바바는 자체 코딩 벤치마크 대부분을 Claude Code 하네스를 사용하여 실행했습니다. Anthropic 엔드포인트는 호환성을 위한 추가 고려 사항이 아니라, 공급업체 자체가 코딩 수치를 산출하는 데 사용한 구성입니다. 에이전트 코딩이 사용 사례라면, 저희 코딩용 Qwen 3.8 분석에서 해당 벤치마크 행과 다른 지원되는 하네스(Codex, Qoder, Qwen Code, OpenClaw 모두 공식 구성 지원)에 대해 자세히 설명합니다.

Claude Code 외에 이중 프로토콜이 중요한 이유는 무엇일까요? 이는 팀이 두 생태계에 걸쳐 코드와 도구를 분할하여 사용할 가능성이 높기 때문입니다. 두 가지 형식에 모두 응답하는 하나의 API는 클라이언트를 먼저 다시 작성하지 않고도 양방향으로 마이그레이션을 테스트할 수 있음을 의미합니다.

비용은 얼마인가요?

요약: 1백만 입력 토큰당 $2, 1백만 출력 토큰당 $6이며, 0에서 1백만 컨텍스트까지 단일 균일 요금입니다. 1백만 컨텍스트 모델 중 드물게 긴 컨텍스트 할증료가 없습니다. 컨텍스트 캐싱은 캐시 적중 시 반복 입력 비용을 입력 가격의 10%로 절감하며, 명시적 캐시 생성은 125%로 청구됩니다. 공식 가격 페이지에서 현재 수치를 확인할 수 있습니다.

비교하자면, 이 출시 가격은 Qwen 3.7-Max의 정가인 $2.5/$7.5보다 저렴합니다. 하지만 스트리밍 섹션의 청구 관련 참고 사항을 기억하세요: 사고 토큰은 출력으로 간주되며, 기본 노력 수준은 xhigh이므로 실제 청구액은 단순한 표시 가격 계산보다 높게 나올 수 있습니다. 자세한 비용 예시와 무료 할당량에 대한 자세한 내용은 전체 Qwen 3.8 가격 분석을 참조하세요.

Apidog에서 Qwen 3.8 API 테스트 및 디버그

이중 프로토콜, 삼중 지역, 스트리밍 추론 API는 제대로 된 API 워크벤치가 진가를 발휘하는 표면입니다. 다음은 Apidog에서 실용적인 설정 방법입니다:

OpenAI 호환 사양 가져오기. 프로젝트를 생성하고 요청 본문 스키마와 함께 채팅 완료 엔드포인트(POST /chat/completions)를 추가하세요. API가 OpenAI 형식을 따르므로, 기존 OpenAI 사양을 가져와 서버 URL 외에는 아무것도 변경하지 않아도 됩니다. 동일한 프로젝트에 Anthropic Messages 엔드포인트를 두 번째 API로 추가하여 두 프로토콜 형태가 나란히 존재하도록 하세요.
지역을 환경으로 모델링. 세 가지 Apidog 환경(베이징, 싱가포르, 미국-버지니아)을 생성하고, 각 환경에 일치하는 호환 모드 URL로 설정된 base_url 변수와 공유 DASHSCOPE_API_KEY 비밀을 설정하세요. 지역 전환은 모든 요청을 편집하는 대신 드롭다운 클릭으로 이루어집니다. 이는 프로덕션에 적용하기 전에 각 지역에 대한 자신의 위치에서의 지연 시간을 확인하는 깔끔한 방법이기도 합니다.
SSE 스트림 검사. "stream": true로 요청을 보내고 응답 보기에서 원시 서버 전송 이벤트를 확인하세요. 먼저 reasoning_content 델타가 도착하고, 그 다음 content 델타가 도착하는 것을 볼 수 있습니다. 프로덕션 환경에서 스트리밍 파서가 오작동할 때, Apidog에서 그 출력을 원시 이벤트 시퀀스와 비교하는 것이 버그가 당신의 것인지 아니면 공급업체의 것인지 알아내는 가장 빠른 방법입니다.
모델들을 나란히 비교. 요청을 복제하고, 모델 ID를 qwen3.7-max로 변경한 다음, 동일한 프롬프트에 대해 두 모델을 모두 실행하세요. 동일한 프로젝트에 Kimi K3 API 요청을 유지하고 실제 워크로드에서 두 오픈 가중치 플래그십 모델을 A/B 테스트하며, 각 실행에 대한 응답 시간과 토큰 수를 기록하는 방식으로 다른 제공업체에서도 동일한 트릭이 작동합니다. 공급업체 벤치마크 테이블은 시작점일 뿐이며, 실제 테스트는 자신의 프롬프트입니다.

함께 따라하려면 Apidog를 무료로 다운로드하세요; 위 전체 설정은 약 10분 정도 소요됩니다.

자주 묻는 질문

Qwen 3.8 API를 무료로 사용해 볼 수 있나요? 네. 새로운 Model Studio 계정에는 qwen3.8-max에 대한 1백만 토큰 무료 할당량이 제공되며, 싱가포르 지역에서만 90일 동안 유효합니다. 이것이 전체 제공 내용이므로, 이를 사용하려면 평가 트래픽을 dashscope-intl을 통해 라우팅하세요.

API 대신 Qwen 3.8을 로컬에서 실행할 수 있나요? 아직은 아닙니다. 알리바바는 다음 주에 Hugging Face와 ModelScope에 오픈 가중치를 제공하겠다고 약속했지만, 2026년 8월 초 현재까지는 다운로드할 수 없습니다. 또한 총 2.4조 개의 매개변수이므로, 양자화하더라도 자체 호스팅은 다중 노드 프로젝트가 될 것입니다. 현재로서는 호스팅된 API가 모델을 실행하는 유일한 방법입니다.

Anthropic 엔드포인트가 OpenAI 엔드포인트와 동일한 기능을 지원하나요? Anthropic 엔드포인트는 Anthropic Messages 프로토콜을 사용하며, 주로 해당 생태계의 도구들을 지원하기 위해 존재하며, Claude Code는 공식적으로 문서화된 통합입니다. 직접적인 애플리케이션 코드의 경우, OpenAI 호환 엔드포인트가 더 잘 문서화된 경로이며, 위에 설명된 reasoning_effort, enable_thinking, 그리고 스트리밍 reasoning_content를 모두 포함합니다.

qwen3.8-max는 코딩 작업에서 Qwen3-Coder와 어떻게 비교되나요? 이들은 다른 도구입니다. Qwen3-Coder는 전문화된 코딩 모델 라인이고, qwen3.8-max는 알리바바 자체 표에서 강력한 에이전트 코딩 수치(공급업체 실행 벤치마크 기준 Terminal Bench 2.1에서 86.6)를 기록한 범용 플래그십 모델입니다. 둘 중 하나를 선택하는 경우, 동일한 API 표면을 통해 둘 다 테스트해 보세요: 모델 ID를 제외하고 호출은 동일합니다.

마무리

Qwen 3.8 API는 채택하기 쉬운 플래그십 출시 중 하나입니다. 기본 URL을 변경하면 OpenAI SDK 코드가 작동하고, 세 가지 환경 변수를 설정하면 Claude Code 설정이 작동하며, $2/$6의 균일 가격은 1백만 컨텍스트에 걸쳐 비용을 예측하기 위해 스프레드시트가 필요 없음을 의미합니다. 실제로 주의해야 할 주요 사항: xhigh 기본 노력 수준에서 출력으로 청구되는 사고 토큰과 무료 할당량의 지역별 분할입니다.

싱가포르의 무료 할당량부터 시작하여, 몇 가지 요청을 스트리밍하여 추론 델타가 어떻게 작동하는지 확인하고, 알리바바의 벤치마크 테이블을 포함한 어떤 벤치마크 테이블도 신뢰하기 전에 자신만의 프롬프트를 통해 테스트해 보세요. 전체를 Apidog에서 프로젝트로 설정하고, 지역을 환경으로, 두 프로토콜을 저장된 요청으로 구성하면, 즉흥적인 cURL로 보내던 오후의 평가가 다음 모델이 출시될 때 팀 전체가 다시 실행할 수 있는 무언가로 바뀝니다.

버튼