Qwen 3.7 Plus는 Alibaba의 멀티모달 에이전트 모델입니다. 텍스트, 이미지, 비디오를 입력으로 받고 1백만 토큰 컨텍스트를 지원하며 API 형태로 제공됩니다. 이 가이드는 API 키 발급, 첫 요청 전송, 이미지/비디오 페이로드 작성, 비용 계산, 속도 제한 대응까지 구현 관점에서 정리합니다.
이 글에서는 Alibaba Cloud Model Studio에서 Qwen 3.7 Plus에 접근하는 방법, Python/curl/JavaScript 예제, 멀티모달 요청 형식, 가격 예시, 오류 처리 방식을 다룹니다. 또한 Apidog로 요청을 테스트하고, 원시 응답을 확인하며, 엔드포인트를 모의(Mock)하는 방법도 함께 설명합니다. 기능과 벤치마크가 먼저 필요하다면 Qwen 3.7 Plus 개요를 참고하세요. 텍스트 전용 플래그십 모델은 기본 Qwen 3.7 API 가이드를 확인하세요.
요약: TL;DR
Qwen 3.7 Plus는 Alibaba Cloud Model Studio, 즉 DashScope의 OpenAI 호환 엔드포인트에서 호출합니다.
구현에 필요한 핵심은 다음과 같습니다.
- 지역별 기본 URL을 설정합니다.
- API 키를 Bearer 토큰으로 전달합니다.
-
/chat/completions엔드포인트를 호출합니다. - 모델 ID는
qwen3.7-plus를 사용합니다. - 이미지와 비디오는
messages[].content배열에 멀티모달 파트로 추가합니다. - 가격은 입력 100만 토큰당
$0.40, 출력 100만 토큰당$1.60, 캐시된 입력 100만 토큰당$0.08입니다. - 영구 무료 계층은 없지만 신규 계정에는 일회성 무료 할당량이 제공됩니다.
- 비전 입력도 컨텍스트와 비용에 포함되므로 이미지/비디오 크기를 관리해야 합니다.
배포 전에는 반드시 Model Studio 모델 목록에서 최신 모델 ID를 확인하세요.
Qwen 3.7 Plus에 액세스하는 방법
Qwen 3.7 Plus는 다운로드해서 자체 호스팅하는 모델이 아닙니다. 실제 통합은 Alibaba Cloud Model Studio API를 통해 진행합니다.
1. Qwen Chat에서 빠르게 평가하기
chat.qwen.ai에 로그인한 뒤 Plus 모델을 선택하면 이미지를 포함한 프롬프트를 바로 테스트할 수 있습니다.
이 방법은 다음에 적합합니다.
- 모델 응답 품질 확인
- 이미지 이해 능력 확인
- 간단한 UI/스크린샷 분석 테스트
하지만 API 통합용은 아닙니다.
2. Alibaba Cloud Model Studio에서 API로 호출하기
운영 통합은 Alibaba Cloud Model Studio, 즉 DashScope에서 진행합니다. DashScope는 OpenAI 호환 API를 제공하므로 기존 OpenAI SDK 기반 코드에서 다음만 바꾸면 됩니다.
base_url- API 키
- 모델 ID
Plus는 독점 모델입니다. 공개 가중치가 없으므로 자체 호스팅이나 에어갭 환경 실행은 불가능합니다. 이 제한은 Qwen 3.7 Plus 개요에서 더 자세히 다룹니다.
| 방법 | API 액세스 | 비용 | 가장 적합한 용도 |
|---|---|---|---|
| Qwen Chat (chat.qwen.ai) | 불가 | 무료, 속도 제한 있음 | 이미지를 사용한 빠른 평가 |
| Model Studio / DashScope | 가능, OpenAI 호환 | 토큰당 지불 | 운영 통합 |
| 자체 호스팅 | 불가 | 해당 없음 | 사용 불가, 가중치 비공개 |
Qwen 3.7 Plus API 키 얻기
API 키는 Alibaba Cloud Model Studio 콘솔에서 생성합니다.
단계
- Alibaba Cloud 계정을 생성합니다.
- Model Studio 콘솔을 엽니다.
modelstudio.console.alibabacloud.com - 사용할 지역에서 Model Studio를 활성화합니다.
- API 키 섹션으로 이동합니다.
- 새 키를 생성합니다.
-
sk-로 시작하는 키를 한 번 복사합니다. - 비밀번호처럼 안전하게 저장합니다.
주의할 점은 키가 지역 범위라는 것입니다. 예를 들어 싱가포르에서 생성한 키는 베이징 엔드포인트에서 인증되지 않습니다.
| 지역 | 기본 URL |
|---|---|
| 싱가포르 | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 |
| 미국, 버지니아 | https://dashscope-us.aliyuncs.com/compatible-mode/v1 |
| 베이징, 중국 | https://dashscope.aliyuncs.com/compatible-mode/v1 |
API 키는 코드에 직접 넣지 말고 환경 변수로 관리하세요.
# macOS / Linux
export DASHSCOPE_API_KEY="sk-your-key-here"
# Windows PowerShell
setx DASHSCOPE_API_KEY "sk-your-key-here"
첫 번째 요청 보내기
Qwen 3.7 Plus 엔드포인트는 OpenAI 호환 형식입니다. OpenAI SDK를 사용하거나 직접 HTTP 요청을 보낼 수 있습니다.
현재 예제의 모델 ID는 qwen3.7-plus입니다. 단, 모델 식별자는 변경될 수 있으므로 배포 전 Model Studio 모델 목록을 확인하세요.
Python 예제
먼저 SDK를 설치합니다.
pip install openai
그다음 DashScope 기본 URL을 지정합니다.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
resp = client.chat.completions.create(
model="qwen3.7-plus",
messages=[
{
"role": "user",
"content": "Qwen 3.7 Plus 가격 모델을 두 문장으로 요약해 주세요.",
}
],
)
print(resp.choices[0].message.content)
지역이 미국 또는 베이징이면 base_url만 해당 지역 URL로 바꾸면 됩니다.
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.7-plus",
"messages": [
{
"role": "user",
"content": "Qwen 3.7 Plus API에서 보냅니다."
}
]
}'
응답에서 확인할 부분은 보통 다음입니다.
{
"choices": [
{
"message": {
"role": "assistant",
"content": "..."
}
}
]
}
JavaScript 예제
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
});
const resp = await client.chat.completions.create({
model: "qwen3.7-plus",
messages: [
{
role: "user",
content: "Qwen 3.7 Plus API에서 보냅니다.",
},
],
});
console.log(resp.choices[0].message.content);
Node.js에서 환경 변수를 사용할 때는 실행 전에 다음처럼 설정합니다.
export DASHSCOPE_API_KEY="sk-your-key-here"
node index.js
이미지 전송하기
Qwen 3.7 Plus를 사용하는 주요 이유는 멀티모달 입력입니다. 이미지는 메시지의 content를 문자열이 아니라 배열로 만들고, 텍스트 파트와 이미지 파트를 함께 전달합니다.
resp = client.chat.completions.create(
model="qwen3.7-plus",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "이 양식을 제출하는 버튼은 무엇인가요? 픽셀 좌표를 알려주세요.",
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/screenshot.png"
},
},
],
}
],
)
print(resp.choices[0].message.content)
이미지는 다음 방식으로 전달할 수 있습니다.
- 공개 접근 가능한 이미지 URL
- base64 데이터 URI
예를 들어 base64 데이터 URI는 다음 형태입니다.
{
"type": "image_url",
"image_url": {
"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}
}
이미지 입력은 GUI 에이전트 작업에 유용합니다. 예를 들어 스크린샷을 보내고 다음과 같은 결과를 요청할 수 있습니다.
로그인 버튼의 위치를 찾아서 click at (x, y) 형식으로 반환하세요.
모델은 다음처럼 구조화된 동작을 반환할 수 있습니다.
click at (x=487, y=232)
비디오 전송하기
비디오도 멀티모달 파트로 전달합니다. 다만 비디오 파트의 정확한 이름과 스키마는 지역 또는 API 호환성 문서에 따라 달라질 수 있습니다.
따라서 구현 전 현재 스키마는 OpenAI 호환성 문서를 확인하세요.
비디오 비용을 줄이려면 다음을 적용하세요.
- 전체 영상을 그대로 보내지 않습니다.
- 필요한 구간만 잘라냅니다.
- 프레임 샘플링 속도를 낮춥니다.
- 해상도를 낮춥니다.
- 텍스트로 설명 가능한 정보는 비디오 대신 텍스트로 제공합니다.
가격
Qwen 3.7 Plus는 Qwen 3.7 Max보다 저렴한 멀티모달 티어로 가격이 책정되어 있습니다.
| 모델 | 입력 / 100만 토큰 | 출력 / 100만 토큰 | 캐시된 입력 / 100만 토큰 |
|---|---|---|---|
| Qwen 3.7 Plus | $0.40 |
$1.60 |
$0.08 |
| Qwen 3.7 Max | $2.50 |
$7.50 |
$0.25 |
입력 기준으로 Plus는 Max보다 약 6배 저렴합니다.
영구적인 무료 계층은 없습니다. 다만 신규 Model Studio 계정은 보통 싱가포르 지역에서 모델을 평가할 수 있는 일회성 무료 토큰 할당량을 받습니다. 이후에는 종량제 방식으로 과금됩니다.
이전 Qwen OAuth 무료 경로는 2026년 4월 15일에 중단되었으므로, 이를 기반으로 개발하지 마세요.
공식 가격과 무료 할당량은 다음 문서에서 확인하세요.
더 넓은 범위의 모델을 무료로 시도하는 방법은 Qwen 3.7 무료 가이드를 참고하세요.
실제 요청 비용 계산
텍스트 요청은 저렴합니다. 비용이 커지는 지점은 이미지와 비디오입니다.
시각적 콘텐츠는 토큰으로 변환되며, 이 토큰은 입력 토큰 요금과 1백만 컨텍스트 예산을 공유합니다.
| 요청 | 입력 토큰 | 출력 토큰 | 대략적인 비용 |
|---|---|---|---|
| 텍스트 전용 프롬프트 | 10,000 | 2,000 | 약 $0.007
|
| 1080p 스크린샷 1개 + 프롬프트 | 약 1,500 | 300 | 약 $0.001
|
| 2fps로 샘플링된 30초 비디오 | 약 77,000 | 500 | 약 $0.032
|
프레임-토큰 수치는 해상도와 샘플링 속도에 따라 달라집니다. 중요한 점은 다음입니다.
- 텍스트 중심 에이전트는 비용이 낮습니다.
- 비디오 중심 작업은 호출당 비용이 크게 증가할 수 있습니다.
- 스크린샷은 필요한 영역만 잘라서 보내는 것이 좋습니다.
- 비디오는 낮은 fps로 샘플링하는 것이 좋습니다.
비용 최적화 전략은 에이전트 토큰 비용 절감 글과 2026년 중국 LLM 가격 전쟁을 참고하세요.
속도 제한 및 오류 처리
Model Studio는 계정별 속도 제한을 적용합니다.
일반적으로 제한은 다음 기준으로 관리됩니다.
- 분당 요청 수
- 분당 토큰 수
- 계정 등급
- 지역
단일 고정 숫자가 아니라 계정과 지역에 따라 달라지므로, 콘솔의 할당량 페이지에서 현재 제한을 확인하세요. 제한에 도달하면 증가 요청을 해야 합니다.
일반적인 오류
| 오류 | 원인 | 대응 |
|---|---|---|
401 Unauthorized |
잘못된 키 또는 지역이 맞지 않는 키 | 키와 base_url 지역을 확인 |
429 Too Many Requests |
속도 제한 초과 | 지수 백오프 후 재시도 |
400 Bad Request |
잘못된 멀티모달 페이로드, 너무 큰 이미지, 컨텍스트 초과 | 요청 스키마와 이미지 크기 확인 |
5xx |
일시적인 서버 오류 | 재시도 로직 적용 |
Python 재시도 예제
429 또는 5xx 응답에 대비해 호출을 재시도 루프 안에 넣는 것이 좋습니다.
import time
from openai import OpenAI
def create_completion_with_retry(client: OpenAI, payload: dict, max_retries: int = 3):
for attempt in range(max_retries):
try:
return client.chat.completions.create(**payload)
except Exception as e:
if attempt == max_retries - 1:
raise
sleep_seconds = 2 ** attempt
print(f"요청 실패, {sleep_seconds}초 후 재시도합니다: {e}")
time.sleep(sleep_seconds)
사용 예시는 다음과 같습니다.
payload = {
"model": "qwen3.7-plus",
"messages": [
{
"role": "user",
"content": "짧게 요약해 주세요.",
}
],
}
resp = create_completion_with_retry(client, payload)
print(resp.choices[0].message.content)
Apidog로 Qwen 3.7 Plus API 테스트 및 모의(Mock)
멀티모달 요청은 실수하기 쉽습니다.
특히 다음 부분에서 오류가 자주 발생합니다.
- 이미지 base64 인코딩
-
content배열 중첩 구조 - 잘못된
type값 - 너무 큰 이미지 또는 비디오
- 도구 호출 루프에서 구조화된 응답 파싱
터미널에서 JSON을 계속 수정하며 확인하는 것은 비효율적입니다.
Apidog를 사용하면 다음 작업을 한곳에서 처리할 수 있습니다.
- Qwen 3.7 Plus 요청 작성
- 이미지/비디오 파트가 포함된 JSON 페이로드 테스트
- 원시 JSON 응답 확인
- 지역별 Model Studio 키를 환경 변수로 저장
- 프런트엔드 개발용 Mock 엔드포인트 생성
- 에이전트 실행 흐름 디버깅
Plus가 GUI 또는 CLI 에이전트에서 도구 호출을 연결할 때는 실행 순서를 추적해야 합니다. 이때 Apidog의 AI 에이전트 디버거를 사용하면 어느 단계에서 응답이 깨졌는지 확인할 수 있습니다.
제품에 연결하기 전에 Qwen 3.7 Plus API를 테스트하고 디버그하며 모의하려면 Apidog를 다운로드하세요.
FAQ
Qwen 3.7 Plus API에 무료 계층이 있나요?
영구적인 무료 계층은 없습니다. 신규 Alibaba Cloud Model Studio 계정은 일반적으로 싱가포르 지역에서 모델을 평가할 수 있는 일회성 무료 토큰 할당량을 받습니다. 이후에는 종량제 방식으로 과금됩니다.
모델 ID는 무엇인가요?
Model Studio에서는 qwen3.7-plus를 사용합니다. 단, 식별자는 변경될 수 있으므로 배포 전 Model Studio 모델 목록에서 현재 문자열을 확인하세요.
이미지 및 비디오 비용은 어떻게 계산되나요?
시각적 콘텐츠는 입력 토큰으로 변환됩니다. 이 토큰은 표준 입력 요금으로 청구됩니다. 1080p 스크린샷은 수천 토큰이 될 수 있고, 비디오는 샘플링된 프레임마다 토큰이 추가됩니다.
Qwen 3.7 Plus API는 Qwen 3.7 Max와 어떻게 다른가요?
동일한 OpenAI 호환 형식과 기본 URL을 사용합니다. Plus는 메시지 콘텐츠에 이미지와 비디오 파트를 허용하며 비용이 약 6배 저렴합니다. Max는 텍스트 전용이며 순수 텍스트 벤치마크에서 약간의 우위를 유지합니다.
Qwen 3.7 Plus를 자체 호스팅할 수 있나요?
아니요. 가중치가 비공개이므로 Alibaba Cloud Model Studio를 통해서만 실행할 수 있습니다.
어떤 기본 URL을 사용해야 하나요?
API 키를 생성한 지역과 일치하는 URL을 사용해야 합니다. 싱가포르, 미국 버지니아, 베이징 중 키를 만든 지역의 엔드포인트를 선택하세요. 다른 지역의 엔드포인트에는 키가 인증되지 않습니다.
결론
Qwen 3.7 Plus 호출은 OpenAI SDK에서 기본 URL, API 키, 모델 ID를 바꾸는 방식으로 구현할 수 있습니다. 텍스트만 보낼 때는 일반 채팅 완료 요청과 거의 동일하고, 이미지나 비디오가 필요할 때는 messages[].content를 배열로 만들어 멀티모달 파트를 추가하면 됩니다.
운영 전에 확인할 것은 세 가지입니다.
- 키와 지역별
base_url이 일치하는지 확인합니다. - 이미지와 비디오 크기를 줄여 토큰 비용을 제어합니다.
- Apidog에서 요청, 응답, Mock 흐름을 먼저 검증합니다.
API 자체는 단순합니다. 실제 비용과 안정성은 얼마나 많은 픽셀과 프레임을 보내는지에 따라 달라집니다.
Top comments (0)