알리바바의 Qwen 모델을 내 코드에서 쓰고 싶은데, 어디서부터 시작해야 할까요? Qwen API는 OpenAI SDK와 호환되기 때문에 기존에 GPT를 써본 분이라면 진입 장벽이 낮습니다. 이 글에서는 계정 만들기부터 Python으로 첫 호출을 보내는 것까지, 실제로 막히기 쉬운 지점 위주로 정리합니다.
Qwen API란
Qwen API는 알리바바 클라우드의 Model Studio(DashScope) 플랫폼을 통해 제공됩니다. Qwen-Max, Qwen-Plus, Qwen-Flash 같은 텍스트 모델 외에 비전, 오디오, 코드 특화 모델까지 API로 호출할 수 있습니다.
핵심은 OpenAI 호환 엔드포인트를 제공한다는 점입니다. Python의 openai 라이브러리에서 base_url만 바꾸면 기존 코드 구조를 거의 그대로 쓸 수 있습니다.
API 키 준비
Qwen API를 쓰려면 알리바바 클라우드 계정이 필요합니다. 국제 사이트(alibabacloud.com)에서 가입하면 됩니다.
가입 시 알아둘 것:
- 중국 전화번호는 필요 없습니다. 한국 번호로 SMS 인증을 받으면 됩니다.
- 가입할 때 선택한 국가/지역이 청구 통화와 세율을 결정하며, 등록 후에는 변경할 수 없습니다. 실제 거주 국가에 맞춰 선택하세요.
- 결제수단은 Visa, Mastercard, JCB 등 국제 카드를 등록할 수 있습니다. 선불·가상·기프트 카드는 지원하지 않습니다.
- 카드 등록 시 3-D Secure 인증과 소액(약 USD 1) 사전 승인이 진행될 수 있습니다.
계정을 만든 뒤 Model Studio 콘솔에서 워크스페이스를 생성하고 API 키를 발급받습니다. API 키는 생성한 리전과 같은 리전에서만 작동하므로, 싱가포르 리전에서 키를 만들었다면 싱가포르 엔드포인트를 써야 합니다.
Qwen API 모델 선택
모델이 많아서 처음에 헷갈립니다. 용도별로 나누면 이렇습니다.
| 용도 | 추천 모델 | 특징 |
|---|---|---|
| 최고 성능이 필요할 때 | qwen3.8-max | 가장 강한 추론 성능 |
| 성능과 비용의 균형 | qwen3.7-plus | 일반 챗봇·글쓰기의 기본값 |
| 대량 처리·비용 우선 | qwen3.8-flash | 속도 빠르고 저렴 |
| 초장문 문서 입력 | qwen-long | 입력 최대 1,000만 토큰 |
| 수학·논리 추론 특화 | qwq-plus | chain-of-thought 추론 전용 |
| 코드 생성 | qwen3-coder-next | 코딩 작업에 최적화 |
처음 시작한다면 `qwen3.7-plus`부터 써보는 걸 권합니다. 성능 대비 가격이 합리적이고, 대부분의 텍스트 작업을 무난하게 처리합니다.
모델 ID에 날짜가 붙은 스냅샷(예: qwen3.7-max-2026-05-20)도 있습니다. 프로덕션에서 결과 재현성이 중요하다면 alias 대신 스냅샷 ID를 쓰는 편이 안전합니다.
Python으로 첫 호출 보내기
openai 라이브러리를 설치한 뒤 base_url만 바꾸면 됩니다.
“`python
pip install -U openai
import os from openai import OpenAI
client = OpenAI( api_key=os.environ[“DASHSCOPE_API_KEY”], base_url=( “https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/” “compatible-mode/v1” ), )
response = client.chat.completions.create( model=”qwen3.7-plus”, messages=[ {“role”: “system”, “content”: “You are a helpful assistant.”}, {“role”: “user”, “content”: “Qwen API를 한 문장으로 설명해 줘.”}, ], )
print(response.choices[0].message.content) “`
{WorkspaceId} 부분을 콘솔에서 확인한 실제 워크스페이스 ID로 교체하세요. model에는 OpenAI 모델명이 아니라 Qwen의 모델 ID를 넣습니다.
기존 공용 도메인(dashscope-intl.aliyuncs.com/compatible-mode/v1)도 작동하지만, 공식 문서는 운영 환경에서 워크스페이스 전용 도메인을 권장합니다.
DashScope 네이티브 SDK를 쓰는 경우
알리바바의 dashscope 패키지는 OpenAI SDK와 별개입니다. 멀티모달 호출이나 DashScope 고유 기능이 필요하면 이쪽을 씁니다.
“`python
pip install -U dashscope
import os import dashscope from dashscope import MultiModalConversation
dashscope.base_http_api_url = ( “https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1” )
response = MultiModalConversation.call( api_key=os.environ[“DASHSCOPE_API_KEY”], model=”qwen3.7-plus”, messages=[ {“role”: “system”, “content”: [{“text”: “You are a helpful assistant.”}]}, {“role”: “user”, “content”: [{“text”: “안녕하세요.”}]}, ], )
print(response) “`
일반적인 텍스트 챗봇이라면 openai SDK로 충분합니다. 두 방식의 차이를 정리하면:
- `openai` + `/compatible-mode/v1`: 기존 GPT 코드 이식에 적합
- `dashscope` + `/api/v1`: 멀티모달, DashScope 고유 기능 사용 시
주요 파라미터
chat.completions.create()에서 자주 쓰는 옵션입니다.
- `model`: 모델 ID.
qwen3.7-plus,qwen3.8-max등. - `messages`: 대화 이력 배열.
system,user,assistant역할을 지정합니다. - `temperature`: 응답의 무작위성. 낮출수록 일관된 답변, 높일수록 다양한 표현.
- `max_tokens`: 출력 토큰 상한.
- `stream`:
True로 설정하면 토큰을 실시간으로 받습니다.
Qwen3 계열의 Thinking 모드를 활성화하면 chain-of-thought 추론을 포함한 응답을 받을 수 있습니다. 이 경우 출력 토큰에 추론 토큰이 포함되며, 요금도 추론 출력 단가가 적용됩니다.
Qwen API 가격
2026년 9월 기준, 베이징 리전의 주요 모델 가격입니다(CNY, 100만 토큰당).
| 모델 | 입력 | 일반 출력 | 비고 |
|---|---|---|---|
qwen3.8-max | ¥12 | ¥36 | 최고 성능 |
qwen3.7-plus | ¥2 | ¥8 | 입력 ≤256K 기준 |
qwen3.8-flash | ¥0.8 | ¥2.7 | 대량 처리용 |
qwen-turbo | ¥0.3 | ¥0.6 | 레거시, 가장 저렴 |
qwen-long | ¥0.5 | ¥2 | 초장문 입력 특화 |
한국에서 흔히 쓰는 싱가포르 리전은 베이징보다 비쌉니다. 예를 들어 싱가포르의 qwen3.8-max는 입력 ¥14.988, 출력 ¥44.965입니다. 반면 qwen3.7-flash는 싱가포르에서도 입력 ¥0.225(≤32K)로 여전히 저렴한 편입니다.
요금 구간은 요청 하나의 총 입력 토큰 수로 정해집니다. 해당 구간의 단가가 그 요청의 모든 토큰에 적용되므로, 입력이 길어질수록 구간이 올라가 단가 자체가 비싸집니다.
무료 체험: 신규 사용자는 Model Studio를 처음 활성화하면 모델별로 약 100만 토큰의 무료 할당을 받습니다. 유효기간은 활성화일로부터 90일입니다. 다만 이 무료 할당은 베이징 리전 전용으로 안내되어 있고, 싱가포르 등 해외 리전의 무료 제공 여부는 공식 문서 간 불일치가 있습니다. 실제 콘솔의 Free Quota 표시를 확인하는 것이 확실합니다.
속도 제한
Qwen API의 Rate limit은 분당 요청 수(RPM)와 분당 토큰 수(TPM)로 관리됩니다.
- 한도는 API 키별이 아니라 알리바바 클라우드 루트 계정 단위로 합산됩니다.
- 대표 예시:
qwen3.7-max는 30,000 RPM / 5,000,000 TPM,qwen-flash는 30,000 RPM / 10,000,000 TPM(베이징 기준). - 일부 최신 모델(
qwen3.8-max등)은 전월 소비 등급에 따라 TPM이 매월 조정되는 동적 제한을 적용합니다. - 한도를 넘으면 HTTP
429오류가 반환됩니다. - 충전만으로 한도가 올라가지 않습니다. 상향이 필요하면 별도로 요청해야 합니다.
실제 활용 시 참고할 점
리전 선택이 중요합니다
Model Studio는 싱가포르, 미국 버지니아, 일본 도쿄, 독일 프랑크푸르트, 홍콩, 베이징 리전을 제공합니다. 리전은 단순한 접속 위치가 아니라 데이터 저장 위치와 추론 범위를 결정합니다. 한국 사용자는 보통 싱가포르를 선택하지만, 모델·API 키·엔드포인트의 리전이 모두 일치해야 합니다. 맞지 않으면 호출 자체가 실패할 수 있습니다.
데이터 보관 정책
알리바바 클라우드는 사용자 데이터를 모델 학습에 사용하지 않는다고 명시합니다. 그러나 법령 준수를 위해 호출 데이터는 저장한다고 밝히고 있습니다. “학습 미사용”이 “데이터 무보관”을 뜻하지 않는다는 점을 알아둘 필요가 있습니다.
콘텐츠 필터링
기본 보안 정책이 적용되며, 별도 유료 Content Moderation을 활성화하면 입력·출력을 더 세밀하게 검사할 수 있습니다. 기본 탐지 범주에는 음란·정치·폭력·악성 프롬프트가 포함됩니다.
시작 전 체크리스트
Qwen API 사용법을 요약하면 이렇습니다.
- 알리바바 클라우드 국제 사이트에서 계정 생성 (한국 번호 가능)
- Model Studio 콘솔에서 워크스페이스 생성, 리전 확인
- API 키 발급
pip install openai로 SDK 설치base_url에 워크스페이스 전용 도메인 설정model에 Qwen 모델 ID 지정 후 호출
처음이라면 qwen3.7-plus로 시작해서 응답 품질과 비용을 확인한 뒤, 필요에 따라 Max나 Flash로 옮기는 게 현실적입니다. 무료 할당이 있는 동안 여러 모델을 비교해 보세요.
