Qwen Image 3.0 API 사용법은? 중국어 포스터를 한 번에 정확하게 쓰기

TL;DR

• Qwen Image 3.0(통이첸원 이미지 3.0)은 HiAPI에서 4개의 엔드포인트를 제공합니다: 표준 버전 qwen-image-3.0/text-to-image, qwen-image-3.0/image-to-image, Pro 버전 qwen-image-3.0-pro/text-to-image, qwen-image-3.0-pro/image-to-image. 모델 페이지를 열면 온라인에서 바로 체험할 수 있습니다.
• 표준 버전은 장당 정액 $0.0358(1K, 2K 동일 가격), Pro는 1K $0.0497, 2K $0.0993입니다. 편집과 생성 가격은 같으며, 참조 이미지 1–3장에는 추가 비용이 없습니다.
• 중국어와 중영문 이중 언어 텍스트가 강점입니다. 호출 방식: POST /v1/tasks에 prompt, aspect_ratio, resolution을 전달하고, success가 될 때까지 폴링한 뒤 다운로드합니다.

먼저 한 장 보기

표준 버전, 16:9, 간판의 중국어를 글자 그대로 정확하게:

qwen-image-3.0/text-to-image, 16:9, $0.0358.

파라미터 빠른 참조

필드	필수	값	설명
prompt	예	최대 18000자	나타날 텍스트를 따옴표 안에 글자 그대로 작성
aspect_ratio	아니오	1:1(기본값) 3:2 2:3 4:3 3:4 16:9 9:16 21:9
resolution	아니오	1K(기본값) / 2K	표준 버전은 두 단계 동일 가격, Pro는 2K가 두 배
output_format	아니오	png(기본값) / jpeg
prompt_extend	아니오	불리언, 기본값 true	프롬프트를 자동 재작성; 텍스트 요구가 정확할 때는 끄기
negative_prompt	아니오	최대 500자	나타나지 않았으면 하는 내용
seed	아니오	0–2147483647	고정하면 재현에 유리
image_urls	편집 엔드포인트 필수	1–3장	JPEG, PNG, WEBP 등, 장당 10 MB 이하

파라미터는 엄격하게 검증되며, 초과 필드를 보내면 400을 반환합니다. 주의: 기존 방식인 "model": "qwen-image-3.0"에 size를 쓰는 것은 더 이상 사용할 수 없으며, 「모델을 사용할 수 없음」 또는 additional properties 'size' not allowed를 반환합니다. 위의 모델명과 aspect_ratio + resolution으로 변경하세요.

curl: 첫 장 성공시키기

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0/text-to-image",
    "input": {
      "prompt": "가을 음료 포스터, 가운데는 계화 라떼 한 잔, 상단 큰 제목에 “가을 한정”을 글자 그대로 쓰고, 아래 부제에 “계화 라떼”를 쓰며, 여백이 충분하고 부드러운 자연광",
      "aspect_ratio": "3:4",
      "resolution": "2K",
      "prompt_extend": false
    }
  }'

반환값에 data.taskId가 있습니다. GET /v1/tasks/{taskId}로 폴링하고, status가 success가 되면 output[0].url에서 다운로드합니다. 표준 버전 2K는 1K와 같은 가격이니 바로 2K를 요청하세요.

Python: 먼저 생성, 그다음 편집

# pip install requests; export HIAPI_KEY=당신의 Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(model, timeout_s=300, **inp):
    # 동일 제출을 재시도할 때 같은 Idempotency-Key를 재사용하면 한 번만 과금됩니다
    r = requests.post(API, json={"model": model, "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(4)
    raise TimeoutError(task_id)

# 텍스트 투 이미지, 표준 버전 2K($0.0358)
poster = run("qwen-image-3.0/text-to-image",
             prompt="차 선물 상자 제품 이미지, 크라프트지 사각 상자 전면에 “운무 녹차”를 쓰고, 아래 작은 글씨로 “내용량 100그램”, 석판 상판, 부드러운 상향광",
             aspect_ratio="1:1", resolution="2K", prompt_extend=False)

# 편집: 어두운 배경으로 바꾸고 텍스트는 그대로(마찬가지로 $0.0358)
edited = run("qwen-image-3.0/image-to-image",
             prompt="선물 상자와 그 위의 텍스트를 완전히 그대로 유지하고, 배경을 짙은 먹색 벨벳으로 바꾸고, 측광 한 줄기 추가",
             image_urls=[poster], aspect_ratio="1:1", resolution="2K")

with open("tea.png", "wb") as f:
    f.write(requests.get(edited).content)

Pro로 바꾸려면 모델명만 바꾸면 됩니다: qwen-image-3.0-pro/text-to-image 또는 qwen-image-3.0-pro/image-to-image, 파라미터는 완전히 동일합니다.

얼마인가

엔드포인트	1K	2K
표준 버전 텍스트 투 이미지 / 이미지 편집	$0.0358	$0.0358
Pro 텍스트 투 이미지 / 이미지 편집	$0.0497	$0.0993

HiAPI 현재 가격, 2026년 10월 18일 확인. 실패 시 과금 없음.

두 단계의 동일 프롬프트 비교는 Qwen Image 3.0 API 가격에서 확인하세요.

출시 전 주의

• 텍스트 요구가 정확할 때는 prompt_extend를 끄세요: 기본적으로 프롬프트를 재작성하며, 원하는 글자를 임의로 바꿀 수 있습니다.
• 나타날 텍스트를 따옴표 안에 글자 그대로 쓰고, 「위 텍스트 외에 다른 텍스트는 넣지 마세요」라는 문장을 추가하세요.
• 폴링 대신 콜백 사용: input과 같은 레벨에 "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"}을 추가하고, taskId로 중복 제거하세요.
• Idempotency-Key 요청 헤더를 포함하세요. 재시도 시 같은 Key는 작업을 한 번만 생성합니다.
• 결과는 즉시 다운로드: output[0].url에는 유효 기간이 있습니다.

자주 묻는 질문

표준 버전과 Pro의 차이는 무엇인가요?

파라미터는 같고, Pro는 화면 디테일과 레이아웃 밀도가 더 높으며, 1K는 약 39% 비싸고 2K는 두 배입니다. 중국어 텍스트는 두 단계 모두 정확하게 씁니다.

이미지 편집 시 최대 몇 장을 전송할 수 있나요?

1–3장, image_urls에 넣으며 추가 비용은 없습니다.

왜 기존 코드가 「model not available」을 반환하나요?

기존 모델명 qwen-image-3.0은 종료되었으므로 qwen-image-3.0/text-to-image로 바꾸세요. size 파라미터도 aspect_ratio와 resolution으로 바뀌었습니다.

바로 모델 페이지에서 중국어 포스터 한 장을 시험해 볼 수도 있습니다.