TL;DR
Qwen Image 3.0는 Standard(qwen-image-3.0)와 Pro(qwen-image-3.0-pro) 두 가지 버전에서 텍스트-투-이미지 생성과 참고 이미지 기반 편집을 통합 제공합니다. 텍스트 프롬프트로 시작해 출력 크기를 선택하고, 이미지 생성 요청을 보낸 뒤 결과를 즉시 저장하세요. 편집 시에는 1–3장의 참고 이미지를 첨부하고 유지해야 할 요소를 명시하세요. CometAPI에서는 샘플 호출을 배포하기 전에 실제 라우트와 호환 요청 스키마를 확인하세요.
Key Takeaways
- Qwen Image 3.0 API는 Standard(qwen-image-3.0)와 Pro(qwen-image-3.0-pro)를 통해 텍스트-투-이미지 생성과 참고 이미지 기반 편집을 지원하며, 기본 출력 형식은 PNG입니다.
- Qwen Image 3.0 API는 CometAPI를 통해 접근할 수 있습니다. 개발자는 API 키를 발급받고, 지원되는 엔드포인트를 확인한 뒤 애플리케이션에 이미지 생성을 통합할 수 있습니다.
- Qwen Image 3.0 API 가격은 CometAPI에서 요청당 $0.024부터 시작하며, Alibaba Cloud Singapore의 Standard 출력 이미지 $0.030, Pro 1K 출력 이미지 $0.040 대비 저렴합니다.
- Qwen Image 3.0 이미지 편집은 Alibaba Cloud 네이티브 API 기준 최대 3장의 참고 이미지를 지원하며, 생성은 요청당 1–6장의 출력을 지원합니다.
- Qwen Image 3.0 API 통합 시, 공급자별 매개변수, 인증, 과금 단위, 임시 이미지 URL을 프로덕션 배포 전에 반드시 확인해야 합니다.
What Is the Qwen Image 3.0 API?
Qwen Image 3.0 API는 텍스트 지시를 이미지로 변환하고, 제공된 사진이나 디자인 에셋을 변형할 수 있습니다. 다국어 포스터, 이커머스 사진, 캠페인 목업, 배경 교체, 합성 이미지 편집 등 다양한 시나리오를 지원합니다.
Qwen Image 3.0 Standard (qwen-image-3.0) 는 비용 최적화된 텍스트-투-이미지 생성 및 참고 이미지 기반 편집의 기준선입니다. 이커머스 배경 변형, 소셜 미디어 비주얼 초안, 캠페인 콘셉트 탐색 등 대량 워크플로에 우선 고려하세요. 예를 들어 Standard로 여러 제품-배경 옵션을 생성한 뒤, 제품 충실도를 검토하고 다듬을 가치가 있는 버전을 선별할 수 있습니다.
Qwen Image 3.0 Pro (qwen-image-3.0-pro) 는 생성과 참고 이미지 기반 편집을 지원하며, 더 높은 가격의 네이티브 2K 출력 티어를 제공합니다. 캠페인 히어로 이미지, 정교한 제품 합성, 프로모션 포스터 등 품질 민감형 결과물에 적합합니다. 예를 들어 디테일이나 레이아웃이 중요한 쇼트리스트 콘셉트에 Pro를 테스트하고, 결과를 Standard와 비교해 추가 비용을 정당화하세요.
선택 방법: 비용에 민감한 초안과 변형에는 Standard로 시작하세요. 동일한 요구사항을 Pro로 테스트해 까다로운 최종 자산이 필요한지 평가하고, 측정 가능한 개선이 추가 비용을 정당화할 때 Pro를 선택하세요. 다만 서체, 제품 충실도, 객체 개수, 레이아웃 정확도 등은 애플리케이션별 테스트가 반드시 필요합니다.
| 사양 | Qwen Image 3.0 | Qwen Image 3.0 Pro |
|---|---|---|
| Model ID | qwen-image-3.0 | qwen-image-3.0-pro |
| 생성 / 편집 | 둘 다 | 둘 다 |
| 편집용 참고 이미지 | 1–3 | 1–3 |
| 요청당 생성 이미지 수 | 1–6 | 1–6 |
| 출력 형식 | PNG | PNG |
| 출력 픽셀 면적 | 512²–2048² | 512²–2048² |
| 권장 프롬프트 길이 | 4,500 tokens | 4,500 tokens |
| 주요 선택 근거 | 비용 효율적 처리량 | 프리미엄 출력 평가 |
What Parameters Does Qwen Image 3.0 API Support?
Alibaba Cloud의 네이티브 OpenAI-호환 인터페이스에서 아래 매개변수를 사용하세요. CometAPI 요청에는 선택한 라우트가 문서화한 경우에만 공급자별 옵션을 추가하세요.
양쪽 버전에 적용: qwen-image-3.0(Standard)과 qwen-image-3.0-pro(Pro)는 Alibaba Cloud의 네이티브 OpenAI-호환 인터페이스에서 아래 동일한 매개변수를 지원합니다. 버전 선택은 model로 하며, 생성과 편집 제어는 공통입니다. 이는 출력 품질이나 가격이 동일함을 의미하지 않으며, 모든 CometAPI 라우트에서 네이티브 매개변수가 그대로 노출됨을 보장하지 않습니다.
| 매개변수 | 형식 / 예시 | 용도 |
|---|---|---|
| model | qwen-image-3.0 | Standard 또는 Pro 선택 |
| prompt | string | 지시와 내용 |
| image | URL / base64 string or array | 편집용 참고 1–3장; 생성 시 생략 |
| size | 1024x1024 | 출력 크기; 지원되는 경우 자동 |
| n | integer 1–6 | 호출당 출력 개수 |
| negative_prompt | string | 피하고 싶은 요소 설명 |
| prompt_extend | boolean | 프롬프트 리라이팅 사용 |
| prompt_extend_mode | direct / agent | 에이전트 모드는 T2I 전용 |
| enable_thinking | boolean | 추론 제어, 강화 설정에 종속 |
| watermark | boolean | 선택적 워터마크 |
| seed | integer | 재현성 보조 |
네이티브 요청에서는 출력 종횡비가 1:8에서 8:1 사이여야 합니다. 참고 이미지는 최대 10 MB, 한 변 길이는 1–8,000픽셀, 긴 변과 짧은 변의 비율은 최대 10:1이어야 합니다. Base64 입력에는 data URI를 사용하세요. Thinking은 prompt_extend=true가 필요하며, 에이전트 강화는 텍스트-투-이미지에만 적용됩니다.
호환 요청에서는 생성 관련 필드를 JSON 최상위에 두고, 크기는 1024x1024 형식으로 작성합니다. 네이티브 DashScope는 input/parameters 중첩 구조를 사용하며 보통 크기를 1024*1024로 표기합니다. 변환 없이 엔드포인트 간 요청을 그대로 복사하면 실패할 수 있습니다.
How Do You Call Qwen Image 3.0 API with CometAPI?
이 가이드는 Python 3, Bash 호환 터미널, 모델 접근 권한이 있는 CometAPI 계정, 충분한 잔액을 전제로 합니다. 첫 번째 요청은 제공자 예시에 나온 model과 prompt 필드만 사용합니다. 문서 확인 일시: 2026년 10월 16일. 아래 예시는 유료 계정에서 실제 실행되지는 않았습니다.
Create credentials
CometAPI 대시보드에서 서버 사이드 API 키를 생성하세요. 웹/모바일 클라이언트에 포함하지 마세요.
export COMETAPI_KEY="your_api_key"python -m pip install requests
Submit a minimal generation request
개발자는 문서화된 이미지 생성 라우트를 통해 CometAPI에서 Qwen Image 3.0 API에 접근할 수 있습니다. 먼저 아래 최소 요청으로 시작한 후 선택적 매개변수를 추가하세요.
curl --fail-with-body https://api.cometapi.com/v1/images/generations \ -H "Authorization: Bearer $COMETAPI_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"qwen-image-3.0","prompt":"Premium skincare bottle on a stone pedestal, gentle studio lighting"}'
Save every returned image
아래 스크립트를 generate.py로 저장하고 python generate.py를 실행하세요. 요청을 전송하고, URL 또는 Base64 이미지 결과를 처리해 각 이미지를 로컬에 저장합니다. 응답이 data 배열 대신 작업 정보(task)를 포함하면, 폴링 엔드포인트를 추측하지 말고 중단하세요. 완료 결과는 계정별 비동기 계약에 따라 조회하세요.
import base64import osfrom pathlib import Pathimport requestsresponse = requests.post( "https://api.cometapi.com/v1/images/generations", headers={"Authorization": f"Bearer {os.environ['COMETAPI_KEY']}"}, json={"model": "qwen-image-3.0", "prompt": "A sunny bookstore cafe, editorial photograph"}, timeout=(15, 600),)response.raise_for_status()result = response.json()images = result.get("data")if not isinstance(images, list) or not images: raise RuntimeError(f"No synchronous images; inspect task/error fields: {list(result)}")for index, item in enumerate(images, 1): if item.get("url"): download = requests.get(item["url"], timeout=(15, 120)) download.raise_for_status() content = download.content elif item.get("b64_json"): content = base64.b64decode(item["b64_json"], validate=True) else: raise RuntimeError(f"Image {index} has no URL or Base64 payload") path = Path(f"qwen_image_{index}.png") path.write_bytes(content) print(f"Saved {path}")
성공적으로 실행되면 로컬 이미지 파일이 생성됩니다. 열어 보아 요청한 장면과 일치하는지 확인하세요. 요청 식별자와 usage 필드는 서버 로그에 보관하되, 자격 증명은 로그에 남기지 마세요.
How Do You Generate Multiple Images with Qwen Image 3.0?
Alibaba Cloud 네이티브 인터페이스에서는 창의적 변형을 위해 n을 2에서 6 사이로 설정하세요. CometAPI에서는 선택한 라우트가 n을 지원하는지 확인한 뒤 사용하세요. 반환된 자산은 각각 검증하세요. n을 크게 설정해도 모든 결과가 후속 검수를 통과한다는 보장은 없습니다.
n 매개변수를 설정하면 Qwen Image 3.0에서 최대 6장의 이미지를 한 번에 생성할 수 있습니다. qwen-image-3.0과 qwen-image-3.0-pro 모두 텍스트-투-이미지 생성과 이미지 편집에 대해 동작합니다. 기본값은 1장입니다.
두 가지 주요 방법이 있습니다. 플랫폼에서 옵션을 제공한다면 그래픽 인터페이스를 사용하거나, API를 직접 호출하세요.
Generate multiple images using the API
- API 문서를 엽니다.
- QwenCloud 콘솔/ CometAPI에서 API 키를 발급받습니다.
qwen-image-3.0또는qwen-image-3.0-pro를 선택합니다.n을 1에서 6 사이의 원하는 이미지 수로 설정합니다.- 프롬프트를 제출하고 반환된 이미지를 저장합니다.
예를 들어 "n": 4로 설정하면 동일한 프롬프트에 대한 4가지 변형을 요청합니다.
Python example
다음은 OpenAI-호환 API를 사용하는, 바로 적용 가능한 예시입니다.
from openai import OpenAIimport requestsclient = OpenAI( api_key="YOUR_QWEN_API_KEY", base_url="https://maas.qwencloudapi.com/compatible-mode/v1")
result = client.images.generate( model="qwen-image-3.0-pro",
prompt=( "A cozy Japanese cafe on a rainy evening, " "warm glowing lights, cinematic photography, " "rich details, realistic reflections" ),
n=4,
size="1024x1024")# Save each generated image
for i, item in enumerate(result.data, start=1): response = requests.get(item.url) response.raise_for_status() with open(f"qwen_image_{i}.png", "wb")
as f:
f.write(response.content)print("Finished generating images!")
먼저 필요한 패키지를 설치하세요.
pip install openai requests
API는 각 결과에 대한 이미지 URL을 반환합니다. 생성된 이미지 URL은 임시이므로 즉시 다운로드하세요.
Important settings
| 매개변수 | 기능 |
|---|---|
| n=4 | 출력 이미지를 4장 생성 |
| model="qwen-image-3.0-pro" | Pro 모델 선택 |
| size="1024x1024" | 정방형 이미지를 요청 |
| seed=12345 | 결과 재현성 향상에 도움 |
| negative_prompt | 원치 않는 시각 요소를 배제 |
요청당 최대 출력 개수는 6장입니다. 더 많은 이미지를 요청하면 생성 비용도 증가합니다.
중요한 차이점: n=4는 하나의 프롬프트에 대한 4가지 변형을 요청한다는 의미입니다. 서로 다른 4개의 프롬프트를 원한다면 별도의 요청을 보내거나 프롬프트를 반복 처리하는 루프를 사용하세요.
How Do You Edit Images with Qwen Image 3.0?
편집은 1–3장의 참고 이미지와 지시를 결합합니다. 원하는 변환과 함께 변경되지 말아야 할 요소(예: 제품 라벨, 색상, 카메라 앵글, 패키지 형상)를 명확히 설명하세요.
다음 예시는 Alibaba Cloud 자격 증명을 사용하고, JSON image 필드를 통한 편집을 보여줍니다. 지역 Model Studio 키를 만들고, 워크스페이스 ID를 확보한 뒤 일치하는 엔드포인트를 구성하세요. 이 요청에 CometAPI 키를 대체 입력하지 마세요.
export DASHSCOPE_API_KEY="your_model_studio_key"export ALIBABA_WORKSPACE_ID="your_workspace_id"export ALIBABA_IMAGE_ENDPOINT="https://${ALIBABA_WORKSPACE_ID}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations"
아래 참고 이미지는 공식 API 예시에서 직접 가져온 입력 이미지입니다. 본 문서에서 생성한 결과물이 아닙니다.
import os, requests
endpoint = os.environ["ALIBABA_IMAGE_ENDPOINT"]
# documented regional .../images/generations endpoint
payload = {
"model": "qwen-image-3.0",
"prompt": "Change the outfit to a charcoal business suit in a cafe. Preserve the face and hairstyle.",
"image": ["https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"],
"size": "1024x1024",
"n": 1}
r = requests.post(endpoint, headers={
"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"}, json=payload, timeout=(15, 600))
r.raise_for_status()
print(r.json())
네이티브 호환 엔드포인트는 /images/generations에서 JSON을 사용하며, /images/edits의 멀티파트 업로드를 사용하지 않습니다. 마스크나 스트리밍을 지원하지 않습니다. 반환된 data 배열을 읽고, 위에서 제시한 다운로드 루프를 사용해 각 URL을 저장하세요.
참고 이미지가 두 개인 경우 image 배열에 두 개의 URL을 포함하고, 프롬프트에서 각 이미지의 역할(예: 1번 이미지의 제품, 2번 이미지의 실내)을 명시하세요. Qwen Image 3.0 시리즈는 참고 이미지를 최대 3장까지만 허용합니다. 더 많은 소스가 필요하면 다른 모델이나 전처리 워크플로를 사용하세요.
How Much Does Qwen Image 3.0 API Cost?
Qwen Image 3.0 API 가격은 모델 버전, 출력 해상도, 공급자에 따라 달라집니다. 아래 표는 원문의 Alibaba Cloud Singapore 비교에, 검토자가 첨부한 가격표에 기반한 CometAPI 요율을 보완해 제공합니다. 첨부 문서는 USD 기준 이미지당 출력 가격과 네 가지 모델/해상도 조합에 대한 20% 할인을 제시합니다. 이 요율은 실제 계정 과금과 독립 재검증되지 않았으므로, 프로덕션 사용 전 적용 요율표를 확인하세요.
| 가격 항목 | Alibaba Cloud Standard | Alibaba Cloud Pro | CometAPI |
|---|---|---|---|
| 입력 참고 이미지 | $0.003/image | $0.003/image | Standard 및 Pro 동일: $0.0024/image |
| 성공한 1K 출력 | $0.030/image | $0.040/image | Standard: $0.0240/image; Pro: $0.0320/image |
| 성공한 2K 출력 | $0.030/image | $0.075/image | Standard: $0.0240/image; Pro: $0.0600/image |
| 100건의 성공한 1K 출력 | $3.00 | $4.00 | Standard: $2.40; Pro: $3.20 (출력 100장 기준)* |
| 1,000건의 성공한 2K 출력 | $30.00 | $75.00 | Standard: $24.00; Pro: $60.00 (출력 1,000장 기준)* |
| 과금 단위 | 입력/출력 이미지 | 입력/출력 이미지 | 첨부 가격표에 따른 과금 가능한 입력 참고 이미지와 성공한 출력 이미지 기준 |
| CometAPI 출력가 할인 | 1K 및 2K에서 20% | 1K 및 2K에서 20% | 입력 및 출력 요율은 첨부 표의 공식 이미지 가격 대비 80% (즉, 20% 할인 적용) |
*위 수량 예시는 출력 이미지에만 해당합니다: 1K Standard 100장은 $2.40, 1K Pro 100장은 $3.20; 2K Standard 1,000장은 $24.00, 2K Pro 1,000장은 $60.00. 편집의 경우 과금 가능한 입력 참고 이미지당 $0.0024를 추가하세요. 실패 과금 규칙, 세금, 계정별 조정은 제외되었습니다.
제공된 입력/출력 이미지 요율을 사용해, 두 공급자 중 어느 쪽이든 이미지 비용을 다음과 같이 추산할 수 있습니다.
Total cost = (billable reference images × input-image price) + (successful outputs × output-image price).
입력 참고 이미지 2장과 성공한 Standard 1K 출력 3장을 과금하는 작업의 경우, Alibaba Cloud 이미지 비용은 (2 × $0.0030) + (3 × $0.0300) = $0.0960입니다. 동일 조건에서 CometAPI 이미지 비용은 (2 × $0.0024) + (3 × $0.0240) = $0.0768입니다(제공된 요율 기준).
CometAPI는 두 버전 모두 입력 참고 이미지당 $0.0024를 과금합니다. 출력 가격은 1K/2K Standard 이미지 $0.0240, 1K Pro 이미지 $0.0320, 2K Pro 이미지 $0.0600입니다. 첨부 표는 각 입력/출력 요율이 해당 공식 요율 대비 20% 낮게 책정되어 있음을 보여줍니다. 동일한 과금 이미지 수라면 이미지 비용도 20% 낮습니다. 추가 수수료나 계정 약관에 따라 최종 청구서는 달라질 수 있습니다.
프로덕션 예산 산정 시, 선택한 버전, 이미지 해상도, 참고 이미지 과금, 요청당 출력 수, 적용 계정 할인 등을 확인한 뒤 총 사용 비용을 추정하세요.
How Do You Handle Qwen Image 3.0 API Errors?
| 증상 | 가능 원인 | 조치 |
|---|---|---|
| 401/403 | 잘못된 키 또는 잘못된 리전 | 자격 증명, 권한, 배포 위치를 확인 |
| 400 invalid image | 참고 이미지 개수/형식 오류 | 1–3장, 유효한 URL/base64, 지원 포맷 사용 |
| 400 invalid size | 지원되지 않는 면적/종횡비 또는 구분자 | 엔드포인트에 맞게 크기 표기를 정규화 |
| Unexpected JSON | 잘못된 엔드포인트 또는 응답 계약 | 응답 필드를 로그하고 파서를 조정 |
| Expired image URL | 만료 전에 이미지를 저장하지 않음 | 생성 직후 즉시 다운로드 및 저장 |
| Unexpected bill | 참고 이미지/출력 티어를 누락하여 고려함 | 이미지 usage 필드와 최신 요율표로 대사 |
| Inconsistent brand text | 생성 모델의 한계 | 검수 게이트 도입 또는 후반 텍스트 오버레이 사용 |
FAQ
타임아웃 후 Qwen Image 3.0 요청을 재시도해야 하나요?
클라이언트 타임아웃은 생성이 중단되었음을 의미하지 않습니다. 요청/작업 식별자를 보관하고, 제공자의 작업 이력이나 상태 API를 확인해 출력이 이미 존재하는지 판별한 뒤 재전송하세요. 무분별한 재시도는 중복 작업과 추가 과금을 초래할 수 있습니다. 일시적 오류에는 제한된 재시도를 사용하고, 가능한 경우 제공자의 멱등성 가이드를 따르세요.
로컬 참고 이미지를 Qwen Image 3.0에서 사용하려면?
네이티브 호환 인터페이스에서는 파일을 바이트로 읽어 Base64 인코딩한 뒤, data:image/png;base64, 같은 data URI 접두사를 붙이세요. 해당 완전한 문자열을 image에 넣습니다. Base64 입력도 이미지 크기 및 해상도 제한을 충족해야 하며, 로컬 파일 경로는 서비스가 가져올 수 있는 URL이 아닙니다.
OpenAI SDK로 Qwen 전용 옵션을 전달하려면?
표준 이미지 필드는 SDK의 일반 인자에 그대로 두고, image와 prompt_extend 같은 Model Studio 확장 필드는 extra_body에 넣으세요. 원시 HTTP 요청은 이러한 필드를 JSON 최상위에 직접 배치합니다. 이 지침은 네이티브 호환 인터페이스에 적용되며, 선택한 CometAPI 라우트에서 공급자별 옵션 전달 방식은 별도로 확인하세요.
요청한 개수보다 적은 이미지가 반환되면?
먼저 성공한 출력을 저장하고 실제 개수를 기록하세요. Alibaba Cloud 네이티브 과금은 성공적으로 생성된 이미지 기준으로 청구됩니다. 추가 자산이 필요하면 응답과 usage 기록을 확인한 뒤 부족한 수량만 요청하세요. CometAPI 과금은 해당 계정 약관에 따라 별도로 대사해야 합니다.
Conclusion
Qwen Image 3.0은 한 모델 계열 내에서 생성과 참고 이미지 기반 편집을 모두 처리해야 하는 팀에 실용적인 선택입니다. 비용 중심의 기준선에는 Standard를, 더 높은 2K 품질이나 창의적 작업에는 Pro를 시험해 보세요. 요청당 비용이 아닌, 최종 채택 출력당 비용을 기준으로 판단하는 것이 중요합니다. 최소 생성 호출로 시작해 출력을 보존하고, 이후 적절한 제공자 계약을 통해 편집이나 다중 출력을 추가하세요. 자격 증명과 요청 스키마를 분리 관리하고, 오류를 명시적으로 처리하며, 선택한 요율표에 맞춰 이미지 사용량을 정산하세요.