Qwen Image 3.0 Pro API 연동: curl, Python 및 전체 파라미터

Qwen Image 3.0 Pro(통이첸원 이미지 3.0 Pro)는 HiAPI에서 두 가지 엔드포인트를 제공합니다: 텍스트→이미지 qwen-image-3.0-pro/text-to-image와 이미지→이미지 qwen-image-3.0-pro/image-to-image입니다. 표준 버전보다 비싼 대신 더 풍부한 디테일과 질감을 얻을 수 있으며, 중문과 영문 텍스트도 정확하게 씁니다. 이 글에서는 바로 실행할 수 있는 curl 및 Python 예제, 현재의 전체 파라미터, 그리고 출시 전에 주의할 몇 가지를 다룹니다.

초기 모델명 qwen-image-3.0-pro와 size 필드는 더 이상 사용할 수 없습니다: 구 모델명은 MODEL_UNAVAILABLE을 반환하고, size는 알 수 없는 필드로 거부됩니다. 위의 두 모델명과 함께 aspect_ratio와 resolution을 사용하세요.

가격부터 확인

	1K(기본)	2K
Pro 텍스트→이미지 / 이미지→이미지	$0.0497	$0.0993
표준 버전 텍스트→이미지 / 이미지→이미지(대조)	$0.0358	$0.0358

HiAPI 현재 가격, 2026년 10월 18일 확인.

Pro 1K는 표준 버전보다 약 39% 비싸고, 2K는 표준 버전의 약 2.8배입니다. 이미지→이미지의 1–3장 참조 이미지는 추가 요금이 없습니다. 실패 시 과금되지 않습니다.

실제 생성 이미지 한 장

16:9. 테이블 위 황동 명판의 「深海来信」와 그 아래 작은 글씨 「LETTERS FROM THE DEEP」가 모두 한 글자도 틀리지 않고 정확히 쓰였습니다:

High-end cinematic architectural editorial photograph inside a futuristic underwater restaurant at midnight. A vast curved observation window fills the background with deep cobalt water and luminous translucent jellyfish drifting outside. On the right, a sculptural dining table of black stone, hand-blown glass and restrained brushed brass catches a narrow beam of warm light. A small refined brass menu plaque on the table is naturally photographed and contains only the exact Chinese characters “深海来信”; directly below, the exact English words “LETTERS FROM THE DEEP”. The left third remains calm dark-blue negative space with volumetric light rays. No poster layout; this must feel like an expensive real location photographed for an architecture magazine. cinematic composition, dramatic directional lighting, rich cohesive cobalt-and-gold color grade, ultra-detailed, premium commercial finish, subtle film grain, shallow depth of field, high dynamic range, 16:9 hero composition

이 프롬프트로 생성하기 →

qwen-image-3.0-pro/text-to-image, 16:9, 모델 페이지 예시 이미지.

첫 이미지 생성 성공시키기

준비: 콘솔에서 API Key를 생성하세요. 신규 사용자 가입 시 200 크레딧이 지급됩니다.

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0-pro/text-to-image",
    "input": {
      "prompt": "一只青瓷茶壶放在胡桃木桌上，清晨的侧光，茶壶旁的小卡片上写着「雨前龙井」",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "prompt_extend": false
    }
  }'

taskId가 반환되면 결과를 조회합니다:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

data.status가 success일 때 이미지는 data.output[0].url에 있습니다. 임시 링크이므로 받은 즉시 다운로드하여 옮겨 두세요.

Python

import os, time, requests

KEY = os.environ["HIAPI_KEY"]
BASE = "https://api.hiapi.ai/v1"
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

r = requests.post(f"{BASE}/tasks", headers=H, json={
    "model": "qwen-image-3.0-pro/text-to-image",
    "input": {
        "prompt": "一只青瓷茶壶放在胡桃木桌上，清晨的侧光，茶壶旁的小卡片上写着「雨前龙井」",
        "aspect_ratio": "4:3",
        "resolution": "1K",
        "prompt_extend": False,
    },
})
task_id = r.json()["data"]["taskId"]

while True:
    d = requests.get(f"{BASE}/tasks/{task_id}", headers=H).json()["data"]
    if d["status"] in ("success", "fail"):
        break
    time.sleep(5)

if d["status"] == "success":
    open("result.png", "wb").write(requests.get(d["output"][0]["url"]).content)
else:
    print(d)

전체 파라미터

필드	필수	값	설명
prompt	예	최대 18000자	화면 내용, 스타일, 구도; 나타낼 글자는 따옴표로 넣어 작성
image_urls	이미지→이미지 필수	1–3장	JPEG/PNG/WEBP/BMP/GIF/TIFF, 장당 ≤10MB, SVG 미지원
aspect_ratio	아니오	1:1(기본), 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9
resolution	아니오	1K(기본)/ 2K	가격 결정
output_format	아니오	png(기본)/ jpeg
prompt_extend	아니오	불리언, 기본 true	프롬프트 자동 재작성; 텍스트를 한 글자도 틀리지 않게 요구할 때는 false로 설정
negative_prompt	아니오	최대 500자	나타내고 싶지 않은 내용
seed	아니오	0–2147483647	고정하면 재현이 용이함

이미지→이미지 예시:

{
  "model": "qwen-image-3.0-pro/image-to-image",
  "input": {
    "prompt": "把这张产品图修成高端杂志风格，保留瓶身形状和标签上的文字",
    "image_urls": ["https://example.com/product.jpg"],
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "prompt_extend": false
  }
}

자주 발생하는 오류

모두 제출 시 동기적으로 HTTP 400이 반환되며, 작업이 생성되지 않고 과금도 되지 않습니다:

• MODEL_UNAVAILABLE: 구 모델명 qwen-image-3.0-pro를 사용한 경우입니다. /text-to-image 또는 /image-to-image가 붙은 이름으로 변경하세요.
• additional properties 'size' not allowed: size는 더 이상 허용되지 않습니다. aspect_ratio와 resolution을 사용하세요.
• resolution: value must be one of '1K', '2K': Pro에는 4K가 없습니다.
• image_urls: minItems: got 0, want 1: 이미지→이미지는 참조 이미지를 최소 1장 전달해야 합니다.

출시 전 주의사항

• 텍스트를 쓸 때는 prompt_extend를 끄세요: 자동 재작성이 원하는 글자를 바꿀 수 있습니다.
• 폴링 대신 콜백 사용: 요청 본문 최상위에 "callback": {"url": "https://你的域名/hiapi/callback", "when": "final"}을 추가하고, taskId로 중복 제거하세요.
• 중복 과금 방지: 제출 시 Idempotency-Key 요청 헤더를 포함하고, 타임아웃 재시도 시에도 동일한 key를 사용하세요.
• 즉시 이전 저장: 출력 링크는 만료됩니다.

자주 묻는 질문

Pro와 표준 버전은 어떻게 선택하나요?

먼저 표준 버전으로 시도해 보세요. 장당 $0.0358이며 1K와 2K 가격이 같습니다. 표준 버전의 디테일이 부족할 때 Pro로 전환하세요. 표준 버전 연동은 Qwen Image 3.0 API 연동을 참고하세요.

4K로 생성할 수 있나요?

아니요, 1K와 2K만 가능합니다.

참조 이미지는 최대 몇 장인가요?

3장이며 추가 요금은 없습니다.

위의 해저 레스토랑 프롬프트를 그대로 복사하여 모델 페이지에서 생성할 수도 있습니다.