DEV Community

Cover image for Qwen 3.8 API 사용법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

Qwen 3.8 API 사용법

알리바바는 2026년 8월 초 Qwen 3.8-Max를 출시했으며, API는 이미 Model Studio에서 사용할 수 있습니다. 이 모델은 총 2.4조 개의 매개변수(활성 950억 개), 100만 토큰 컨텍스트 창, 입력 100만 토큰당 $2 / 출력 100만 토큰당 $6의 균일한 가격을 제공합니다. 모델의 배경과 특성이 필요하다면 Qwen 3.8 설명서를 먼저 확인하세요. 이 글에서는 API 키 발급, 리전 선택, 첫 요청 실행, 스트리밍 및 도구 연결까지 실제 구현 절차를 다룹니다.

지금 Apidog 사용해 보기

Qwen 3.8-Max는 출시 시점부터 두 가지 프로토콜을 지원합니다.

  • OpenAI 호환 엔드포인트: 기존 OpenAI SDK 코드에 기본 URL과 모델 ID만 바꿔 적용할 수 있습니다.
  • Anthropic 호환 엔드포인트: Claude Code 같은 Anthropic 생태계 도구를 환경 변수 설정으로 연결할 수 있습니다.

이 이중 프로토콜 구조는 Apidog에서 같은 프롬프트를 두 요청 형식으로 테스트하고, 각 프로토콜의 스트리밍 응답을 비교할 때 특히 유용합니다.

시작하기 전에 필요한 것

항목 값
모델 ID qwen3.8-max
컨텍스트 창 1,000,000 토큰
최대 출력 65,536 토큰
입력 유형 텍스트 및 이미지
가격 입력 100만 토큰당 $2 / 출력 100만 토큰당 $6
추론 제어 reasoning_effort: xhigh(기본), medium, low
프로토콜 OpenAI Chat Completions + Responses, Anthropic Messages
API 키 환경 변수 DASHSCOPE_API_KEY

위 정보는 공식 Qwen 3.8 출시 게시물과 Alibaba Cloud Model Studio 문서를 기준으로 합니다. 알리바바는 다음 주 Hugging Face와 ModelScope에 오픈 가중치를 제공하겠다고 밝혔지만, 2026년 8월 초 기준 가중치는 아직 다운로드할 수 없습니다. 따라서 이 글의 예제는 모두 호스팅 API 기준입니다.

1단계: QwenCloud에서 API 키 발급하기

home.qwencloud.com에 접속해 로그인하거나 계정을 만드세요. 콘솔에서 API 키를 생성한 뒤 셸 환경 변수에 저장합니다.

Alibaba 플랫폼은 내부적으로 DashScope 이름을 사용하므로 환경 변수 이름은 DASHSCOPE_API_KEY입니다.

export DASHSCOPE_API_KEY="sk-your-key-here"
Enter fullscreen mode Exit fullscreen mode

키를 소스 코드에 직접 작성하지 마세요. 로컬 개발에서는 .env 파일 또는 셸 프로필에 저장하고, 배포 환경에서는 시크릿 관리 도구를 사용하는 것이 좋습니다.

# .env 예시
DASHSCOPE_API_KEY=sk-your-key-here
Enter fullscreen mode Exit fullscreen mode

실제 과금 전에 평가하려면 싱가포르 리전을 사용하세요. 싱가포르 리전에서는 90일 동안 사용할 수 있는 100만 토큰 무료 할당량이 제공됩니다.

2단계: 사용할 리전의 기본 URL 선택하기

Model Studio는 세 리전에서 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은 대부분의 국제 사용자에게 적합하며, 무료 할당량도 이 리전에서 사용할 수 있습니다.

Model Studio 모델 목록에 따르면 qwen3.8-max는 텍스트 생성뿐 아니라 이미지와 비디오 이해도 지원하며, 8월 3일 업데이트 기준 추천 모델 목록 상단에 표시됩니다.

이후 예제는 싱가포르 리전을 사용합니다. 베이징 또는 버지니아가 더 가깝다면 base_url만 교체하면 됩니다.

3단계: OpenAI SDK로 첫 요청 보내기

Qwen 3.8-Max는 OpenAI Chat Completions 형식과 호환됩니다. Python에서는 공식 openai SDK를 그대로 사용할 수 있습니다.

먼저 SDK를 설치합니다.

pip install openai
Enter fullscreen mode Exit fullscreen mode

그다음 DashScope 호환 URL을 base_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)
Enter fullscreen mode Exit fullscreen mode

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

기존에 OpenAI 호환 모델을 사용했다면 마이그레이션 작업은 단순합니다.

  1. base_url을 DashScope URL로 변경합니다.
  2. 모델 ID를 qwen3.8-max로 변경합니다.
  3. 기존 메시지 형식과 SDK 호출 구조를 유지합니다.

이전 세대에서 전환하는 경우 Qwen 3.7 Plus API 가이드와 호출 흐름은 동일합니다.

4단계: 스트리밍 응답과 추론 데이터 처리하기

Qwen 3.8-Max는 기본적으로 추론을 수행하는 모델입니다. 스트리밍 모드에서는 최종 응답인 content보다 먼저 사고 과정이 reasoning_content 델타로 도착할 수 있습니다.

UI나 로그에서 두 값을 구분해 처리하세요.

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)
Enter fullscreen mode Exit fullscreen mode

구현 시 다음 두 가지를 고려하세요.

  • reasoning_content 토큰은 출력 토큰으로 계산되므로 비용에 포함됩니다.
  • 기본 추론 수준은 xhigh입니다. 정확도에는 유리하지만, 응답 지연과 출력 토큰 수가 증가할 수 있습니다.

프로덕션 채팅 UI에서는 사고 과정을 사용자에게 노출할지, 서버 로그에만 기록할지, 아예 무시할지를 먼저 결정하는 것이 좋습니다.

5단계: reasoning_effort와 사고 플래그 조정하기

reasoning_effort는 다음 세 가지 값을 지원합니다.

  • xhigh: 기본값. 복잡한 분석, 에이전트 코딩, 어려운 문제에 적합
  • medium: 정확도와 지연 시간의 균형이 필요한 경우
  • low: 분류, 추출, 단순 질의, 대량 처리에 적합

높은 추론 수준은 더 많은 사고 토큰과 높은 지연 시간 및 비용으로 이어질 수 있습니다.

추론 동작은 다음 확장 필드로 제어할 수 있습니다.

  • enable_thinking: 추론 프로세스 활성화 여부
  • preserve_thinking: 대화 턴 사이에서 추론 컨텍스트 유지 여부. 기본값은 활성화입니다.

OpenAI SDK에서는 DashScope 확장 필드를 extra_body로 전달합니다.

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

print(completion.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

권장 시작점은 다음과 같습니다.

워크로드 권장 reasoning_effort
에이전트 코딩, 복잡한 분석 xhigh
일반적인 기술 질의, 다단계 작업 medium
분류, 추출, 간단한 채팅, 대량 요청 low

사고 기능을 켜거나 끄는 것 자체가 토큰 단가를 바꾸는 것은 아닙니다. 실제 비용에는 생성된 사고 토큰 수가 영향을 주며, 이 수량은 reasoning_effort에 직접 영향을 받습니다. 운영 환경에 적용하기 전에는 실제 프롬프트와 응답 길이를 기준으로 벤치마크하세요.

Anthropic 호환 엔드포인트 사용하기

Qwen 3.8-Max는 OpenAI 호환 API 외에 Anthropic Messages 프로토콜용 엔드포인트도 제공합니다.

https://dashscope-intl.aliyuncs.com/apps/anthropic
Enter fullscreen mode Exit fullscreen mode

이 엔드포인트를 사용하면 Claude API용으로 만든 일부 도구를 Qwen 3.8-Max에 연결할 수 있습니다. 대표적인 사례가 Claude Code입니다.

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
Enter fullscreen mode Exit fullscreen mode

이후 claude를 실행하면 Claude Code가 Qwen 3.8-Max를 대상으로 에이전트 루프를 수행합니다.

알리바바는 자체 코딩 벤치마크의 상당수를 Claude Code 하네스로 실행했습니다. Anthropic 엔드포인트는 단순한 형식 변환용 기능이 아니라, 공급업체가 코딩 평가에 사용한 구성과도 연결됩니다. 에이전트 코딩이 주요 목적이라면 코딩용 Qwen 3.8 분석에서 벤치마크 행과 지원 하네스(Codex, Qoder, Qwen Code, OpenClaw)를 확인하세요.

두 프로토콜을 모두 지원하면 OpenAI 및 Anthropic 생태계에 나뉘어 있는 도구를 한 모델로 테스트할 수 있습니다. 클라이언트 코드를 전면 재작성하기 전에 마이그레이션 가능성을 검증하는 데 유용합니다.

비용 계산하기

Qwen 3.8-Max의 기본 가격은 다음과 같습니다.

  • 입력 100만 토큰당 $2
  • 출력 100만 토큰당 $6
  • 컨텍스트 길이 0~100만 토큰에 동일한 요금 적용

100만 컨텍스트 모델 중에서는 긴 컨텍스트에 대해 별도 할증료가 없는 구조입니다.

컨텍스트 캐싱의 경우:

  • 캐시 적중 입력: 일반 입력 가격의 10%
  • 명시적 캐시 생성: 일반 입력 가격의 125%

현재 가격은 공식 가격 페이지에서 확인하세요.

출시 가격은 Qwen 3.7-Max의 정가인 입력 $2.5 / 출력 $7.5보다 낮습니다. 다만 기본 추론 수준이 xhigh이고 사고 토큰도 출력으로 과금되므로, 실제 비용은 표시된 단가만으로 계산한 예상보다 높을 수 있습니다.

구체적인 비용 예시와 무료 할당량은 Qwen 3.8 가격 분석에서 확인할 수 있습니다.

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

리전 3개, 프로토콜 2개, 스트리밍 추론까지 포함된 API는 재현 가능한 테스트 환경으로 관리하는 편이 좋습니다. Apidog에서 다음과 같이 구성하세요.

  1. OpenAI 호환 사양을 가져옵니다.

    프로젝트를 만든 뒤 POST /chat/completions 엔드포인트를 추가합니다. Qwen API는 OpenAI 형식을 따르므로 기존 OpenAI 사양을 가져온 뒤 서버 URL과 모델 ID만 변경할 수 있습니다. 같은 프로젝트에 Anthropic Messages 엔드포인트를 추가하면 두 프로토콜을 나란히 관리할 수 있습니다.

  2. 리전을 환경으로 분리합니다.

    베이징, 싱가포르, 미국-버지니아 환경을 각각 만듭니다. 각 환경에 base_url 변수를 설정하고 DASHSCOPE_API_KEY는 공유 비밀 변수로 관리하세요.

   base_url = https://dashscope-intl.aliyuncs.com/compatible-mode/v1
Enter fullscreen mode Exit fullscreen mode

이렇게 구성하면 모든 요청 URL을 수정하지 않고 환경 드롭다운으로 리전을 전환할 수 있습니다. 배포 전 리전별 지연 시간을 비교하는 데도 유용합니다.

  1. SSE 스트림을 원본 이벤트로 확인합니다. 요청 본문에 "stream": true를 넣고 응답 뷰에서 서버 전송 이벤트를 검사하세요. 일반적으로 reasoning_content 델타가 먼저 도착하고, 이후 content 델타가 이어집니다.

프로덕션에서 스트리밍 파서 문제가 발생하면 애플리케이션 로그와 Apidog의 원본 이벤트 순서를 비교하세요. 클라이언트 파서 문제인지 공급업체 응답 문제인지 빠르게 분리할 수 있습니다.

  1. 모델을 같은 프롬프트로 비교합니다. 요청을 복제한 뒤 모델 ID를 qwen3.7-max로 바꾸고 같은 입력을 실행하세요. 응답 시간, 출력 토큰 수, 최종 결과를 기록하면 실제 워크로드 기준 비교가 가능합니다.

같은 방식으로 Kimi K3 API 요청도 프로젝트에 저장해 다른 제공업체 모델과 A/B 테스트할 수 있습니다. 공급업체 벤치마크는 출발점일 뿐이며, 최종 판단은 자체 프롬프트와 데이터로 해야 합니다.

Apidog를 무료로 다운로드한 뒤 위 구성을 만들면 약 10분 안에 반복 가능한 평가 환경을 준비할 수 있습니다.

자주 묻는 질문

Qwen 3.8 API를 무료로 사용할 수 있나요?

네. 새 Model Studio 계정에는 qwen3.8-max용 100만 토큰 무료 할당량이 제공됩니다. 다만 싱가포르 리전에서만 사용할 수 있고 유효 기간은 90일입니다.

무료 할당량을 사용하려면 요청을 다음 엔드포인트로 보내세요.

https://dashscope-intl.aliyuncs.com/compatible-mode/v1
Enter fullscreen mode Exit fullscreen mode

API 대신 Qwen 3.8을 로컬에서 실행할 수 있나요?

2026년 8월 초 기준으로는 아직 불가능합니다. 알리바바는 Hugging Face와 ModelScope에 오픈 가중치를 제공하겠다고 밝혔지만, 아직 다운로드할 수 없습니다.

또한 총 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입니다.

둘 중 하나를 선택해야 한다면 모델 ID만 바꿔 동일한 API 요청과 실제 작업 프롬프트로 테스트하세요.

마무리

Qwen 3.8-Max는 기존 코드에 적용하기 쉬운 플래그십 API입니다. OpenAI SDK 사용자는 기본 URL과 모델 ID를 변경하면 되고, Claude Code 사용자는 환경 변수 세 개를 설정하면 됩니다.

구현 시 특히 확인할 항목은 다음과 같습니다.

  • 기본값인 xhigh 추론 수준
  • 출력 토큰으로 과금되는 사고 토큰
  • 싱가포르 리전에만 적용되는 무료 할당량
  • 리전별 지연 시간
  • OpenAI 및 Anthropic 프로토콜별 스트리밍 처리 차이

싱가포르 무료 할당량으로 시작해 스트리밍 응답의 reasoning_content와 content 순서를 확인하세요. 이후 실제 프롬프트로 모델을 비교하고, Apidog에 리전별 환경과 프로토콜별 저장 요청을 구성하면 다음 모델 출시 때도 같은 평가 절차를 팀 전체에서 재사용할 수 있습니다.

Top comments (0)