Qwen API 사용법: API 키·리전별 Base URL·Python 첫 호출

Qwen API를 OpenAI Python SDK로 부르려면 Model Studio API 키, 같은 리전의 Base URL, 모델 ID 세 값을 맞추면 된다. 리전마다 API 키와 모델 목록이 따로라 서로 섞어 쓸 수 없다. 운영 환경에는 Workspace 전용 주소를 권장한다. (리전과 주소)

API 키 만들기

1. Alibaba Cloud 계정으로 Model Studio를 켠다.
2. 콘솔 오른쪽 위에서 리전을 먼저 고른다. 키는 리전별로 따로다.
3. API Key 화면에서 키를 만든다. 모델을 미리 고를 필요는 없고, 요청의 model 값으로 정한다.
4. 여러 Workspace를 쓰는 조직이라면 키가 속한 Workspace를 기록해 둔다.

(첫 API 호출) 아래 주소에는 종량제(pay-as-you-go) 키를 쓴다. Token Plan이나 Coding Plan은 코딩 도구용 전용 키와 주소를 쓰니 상품 종류부터 확인한다. (Base URL 안내)

$env:DASHSCOPE_API_KEY="YOUR_API_KEY"

키는 코드에 적지 말고 환경 변수에 둔다. 로그에 인증 헤더가 남지 않게 가리고, 노출됐다면 폐기하고 새로 만든다.

Python으로 첫 요청

Alibaba 문서는 Python 3.9 이상을 적지만, 최신 OpenAI Python SDK는 3.10 이상이 필요하다. python -V로 확인하고 python -m pip install -U openai로 설치한다. 아래 코드를 hello_qwen.py로 저장하고 YOUR_WORKSPACE_ID를 콘솔의 실제 값으로 바꾼 뒤 실행한다(싱가포르 리전 예).

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://YOUR_WORKSPACE_ID.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
response = client.chat.completions.create(
    model="qwen3.8-max",
    messages=[{"role": "user", "content": "가격 1200원인 물건 3개의 합계를 숫자와 원 단위로 답해줘."}],
)
choice = response.choices[0]
print("finish_reason:", choice.finish_reason)
print("answer:", choice.message.content)
print("usage:", response.usage)

연결 성공과 답의 정확성은 따로 본다. 답이 비어 있지 않고, 이 단순 텍스트 예제의 finish_reason이 stop이고, 계산 결과가 3,600원이면 성공이다. usage의 토큰과 콘솔의 해당 Workspace 사용량을 함께 확인한다. 응답의 토큰 수만으로 Workspace를 식별할 수는 없다.

리전별 Base URL

리전	Workspace 전용 OpenAI 호환 주소
싱가포르	https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
도쿄	https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
홍콩	https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
버지니아(미국)	https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
프랑크푸르트(독일)	https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
베이징(중국)	https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

(OpenAI 호환 Chat) 콘솔의 Workspace 관리 화면에서 API Host를 그대로 복사하는 것이 가장 정확하다. 예전 dashscope*.aliyuncs.com 공유 주소는 기존 연동용으로 남아 있다. 다른 모델을 쓰려면 그 리전의 Available Models에서 정확한 모델 ID를 확인하고, 이미지 입력이나 도구 호출 같은 기능 지원도 따로 본다. 모델 비교는 Qwen3.8 모델 비교에 있다.

오류가 날 때

키의 상품 종류 → 리전 → Workspace → 모델 ID 순서로 맞는지 본다.

증상	먼저 확인할 것
401	키가 틀렸거나, 키 종류(종량제·Token Plan·Coding Plan)나 리전이 주소와 다르다
403, Model.AccessDenied	키의 모델 접근 범위, 그 리전에서 모델을 쓸 수 있는지
모델 없음	그 리전의 Available Models에서 정확한 ID
연결 실패	주소의 {WorkspaceId} 치환, 리전 코드, 회사 프록시·방화벽
과금·한도 오류	키가 속한 상품의 잔액·할당량

키가 맞아 보여도 상품·리전·Workspace가 주소와 맞는지 확인한다. 공식 Base URL 안내도 상품과 주소가 다르면 401이 날 수 있다고 설명한다. API Key 화면의 리전, Workspace의 API Host, 코드의 base_url을 나란히 놓고 본다.

자주 묻는 질문

한국에서는 어느 리전을 고르나? 가까운 싱가포르나 도쿄가 무난하다. 다만 쓰려는 모델이 그 리전에 있는지부터 Available Models에서 본다. 리전은 접속 지점·데이터 저장 위치이고, 실제 추론 위치는 서비스 배포 범위(scope)도 함께 결정한다. 회사의 처리 지역 조건이 있다면 두 값을 모두 확인한다.

기존 OpenAI 코드를 Qwen으로 바꾸려면? 위 Chat Completions 기본 예제는 API 키, base_url, 모델 ID를 맞춰 호출한다. 기존 코드에 추가 옵션이 있다면 호환 여부도 확인한다. 그다음 서비스에서 실제로 쓰는 구조화 출력(JSON), 도구 호출, 이미지 입력을 하나씩 시험한다. 도구 호출은 반환된 도구 이름과 인자를 파싱해 결과를 돌려주는 흐름까지 확인한다.

요금과 사용량은 어디서 보나? Model Studio 콘솔의 사용량 화면에서 본다. 가격과 무료 할당량은 리전·모델마다 다르니 콘솔과 모델 가격 페이지를 확인한다.

입력비 줄이기: Context Cache

같은 문서나 규칙을 여러 번 보내면 Context Cache로 입력 비용을 줄인다. 싱가포르에서는 qwen3.8-max와 qwen3-coder-plus가 지원한다. (Context Cache)

항목	자동(implicit)	직접 지정(explicit)
켜는 법	설정 없이 자동	메시지에 "cache_control": {"type": "ephemeral"}
최소 입력	1,024토큰	표시한 곳까지 1,024토큰
생성 단가	일반 입력의 100%	보통 125%
적중 단가	보통 20%	보통 10%
유지 시간	보장 없음	5분(적중하면 다시 5분)

• 바뀌지 않는 내용을 앞에 둔다. 규칙·공통 문서를 먼저, 매번 바뀌는 질문을 뒤에 둔다.
• 두 번 호출하고 두 번째에 적중한다면 위 통상 요율에서 공통 입력 비용 C는 자동 1.20C, 직접 지정 1.35C다. 적중하지 않은 토큰·출력·모델별 예외 요율은 별도로 계산한다.
• qwen3.8-max는 통상 비율과 달라 따로 계산한다. 싱가포르 단가는 일반 입력 $2/M, 자동 적중 $0.25/M, 직접 생성 $2.50/M, 직접 읽기 $0.17/M다(9월 29일 기준). (Qwen3.8-Max 가격)
• 적중은 usage.prompt_tokens_details.cached_tokens로 확인한다. 0이면 모델·리전·배포 범위와 공통 접두문, 1,024토큰 조건을 확인한다. 5분 제한은 직접 지정 방식에 적용되며, 자동 방식은 조건을 맞춰도 적중을 보장하지 않는다.