hiapi API로 qwen-image-2.0을 사용해 이커머스 제품 이미지 생성하기

qwen-image-2.0은 알리바바의 2세대 텍스트-투-이미지 모델로, hiapi의 /v1/tasks 인터페이스를 통해 제공되며 가격은 이미지당 $0.025, 기본 출력은 2K입니다. 이커머스 관점에서 특히 흥미로운 두 가지가 있습니다. 이 가격대에서 중국어 텍스트 렌더링이 현재 모든 텍스트-투-이미지 모델 중 가장 깔끔하고, 길고 상세한 제품 브리프에 대한 프롬프트 순응도가 매우 안정적이라는 점입니다. 바로 크로스보더 리스팅에 실제로 필요한 것입니다.

이 가이드는 이 워크플로의 실행 가능한 버전입니다. 모든 API 호출은 터미널에 그대로 붙여넣을 수 있는 내용이고, 프롬프트 템플릿은 실시간 엔드포인트에서 렌더링을 테스트한 것이며, 이미지당 가격은 HiAPI 가격의 실시간 수치입니다. 여기에는 이론적인 내용이 없습니다. 비용 수치는 마케팅 숫자가 아니라 qwen-image-2.0이 실제로 허용하는 size 값을 기준으로 한 것입니다.

크로스보더 제품 이미지에 qwen-image-2.0을 선택하는 이유

200개의 SKU를 한 번에 마켓 리스팅에 올릴 때 중요한 세 가지가 있습니다.

1. 중국어 텍스트 렌더링. 중국 본토, 홍콩, 대만 또는 동남아에서 판매되는 대부분의 이커머스 리스팅은 패키지, 배너 또는 라벨에 읽을 수 있는 중국어가 필요합니다. qwen-image-2.0은 hiapi에서 “병 라벨에 굵은 세리프 중국어로 玫瑰精华水라고 적혀 있다”와 같은 프롬프트를 쓰면 모델이 설명한 정확한 위치에 정확한 글자를 렌더링해 주는 유일한 모델입니다.
2. 긴 제품 브리프에 대한 프롬프트 순응도. 이커머스 브리프는 깁니다. 소재, 색상 헥스 코드, 표면 처리, 조명 방향, 그림자 모양, 배경색, 카메라 각도까지. 브리프가 길어져도 qwen-image-2.0은 전체적인 일관성을 유지합니다. 실패 모드는 보통 소품 하나를 빠뜨리는 정도이지, 제품을 지어내는 것이 아닙니다.
3. 변형 폭증을 견디는 비용 구간. 일반적인 SKU 페이지에는 4~6장의 이미지(스튜디오 컷, 장면 컷, 탑다운 컷, 비율 비교, 변형 두 개)가 필요합니다. 이미지당 $0.025면 SKU당 $0.10~$0.15입니다. 200 SKU 신상품 런칭이면 $20~$30이 듭니다. 바로 이 비용 구간 덕분에 “전부 처음부터 생성”하는 것이 일부 촬영을 의뢰하고 스톡으로 채우는 것보다 더 저렴해집니다.

프롬프트별 튜닝 실험과 이커머스가 아닌 스타일 중심의 여섯 가지 레시피를 보고 싶다면 동반 글 qwen-image-2.0 프롬프트 레시피를 참고하세요. 이 글은 카탈로그 사용 사례에 집중합니다.

hiapi에서 qwen-image-2.0의 입력 스키마

qwen-image-2.0은 통합 /v1/tasks 인터페이스에서 실행되며, 이는 현재 hiapi가 제공하는 유일한 이미지 엔드포인트입니다. 코드를 작성하기 전에 먼저 제대로 알아 두어야 할 특수 규칙이 하나 있습니다:

• 크기 파라미터 이름은 size입니다. aspect_ratio도, resolution도, image_size도 아닙니다. hiapi의 다른 모델(nano-banana, flux 계열)은 aspect_ratio를 허용하지만 qwen-image-2.0은 허용하지 않습니다.
• size 내부 구분자는 *이며 x가 아닙니다. "size": "2688x1536"은 400을 반환합니다. "size": "2688*1536"만 정상 동작합니다.
• size 값은 다섯 개만 허용됩니다. 모두 2K입니다:

화면 비율	size 값	용도
16:9 (약 1.75:1)	2688*1536	메인 비주얼, 배너, 리스팅 커버
4:3 (약 1.37:1)	2368*1728	매거진형 스프레드, 2단 광고 지면
1:1	2048*2048	정사각 스튜디오 컷, 마켓 썸네일
3:4 (약 0.73:1)	1728*2368	모바일 우선 제품 페이지
9:16 (약 0.57:1)	1536*2688	세로형 비디오 커버, TikTok/Reels 정지 프레임

다른 값을 제출하면 API가 오류에 허용 목록을 그대로 반환합니다:

{"code": 400, "message": "invalid input: size: value must be one of '2688*1536', '2368*1728', '2048*2048', '1728*2368', '1536*2688'"}

이 오류 메시지를 권위 있는 사실 출처로 삼으세요. 나중에 여기에 새 값이 보인다면 플랫폼이 스키마를 확장한 것입니다.

실행 가능한 요청 하나

전체 호출 표면은 두 엔드포인트뿐입니다. POST /v1/tasks는 대기열 등록, GET /v1/tasks/{taskId}는 폴링용입니다. 아래 스튜디오 컷을 만들어 내는 최소 요청입니다.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "input": {
      "prompt": "A clear glass cosmetic dropper bottle on a clean off-white seamless paper background, soft daylight from camera left, gentle elliptical shadow, the label reads 玫瑰精华水 in bold serif Chinese with a small line of English Rose Essence Water below, the liquid inside has a faint pink tint, studio product photography, sharp focus on the label, no other props, square 1:1 composition",
      "size": "2048*2048"
    }
  }'

응답:

{"code": 200, "data": {"taskId": "tk-hiapi-01KW8R..."}, "message": "success"}

폴링용:

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

status 필드는 handling → archiving → success 순으로 진행됩니다. 우리 테스트 실행에서 2K 기준 이미지당 총 실제 소요 시간은 25~45초였습니다. status가 success일 때 output[0].url에 이미지가 저장되지만, 이 URL은 temp.hiapi.ai를 가리키며 expireAt Unix 타임스탬프가 붙어 있으므로 즉시 다운로드해야 합니다. 페이지에 임베드하거나 데이터베이스에 고정하지 마세요. 몇 시간 안에 404가 됩니다.

이 스튜디오 프롬프트를 실시간 엔드포인트에서 실행하면 유리 스포이트 병이 생성되고, 라벨에 중국어 玫瑰精华水가 깔끔하게 렌더링되며 바로 아래에 더 작은 굵기의 영어 Rose Essence Water가 표시됩니다. 모델은 두 줄 텍스트를 규격 라벨 영역에 배치하며, 프롬프트에 레이아웃 힌트가 전혀 필요 없습니다. “the label reads X”라는 표현만으로 충분합니다.

SKU 표를 업로드된 스튜디오 컷으로 바꾸는 Python 루프

이 페이지의 이미지를 생성할 때 우리가 실행한 루프입니다. (slug, prompt, size) 튜플 목록을 받아 작은 동시성 한도로 병렬 제출하고, 각 작업이 끝날 때까지 폴링하고, 결과를 다운로드한 뒤 webp로 여러분의 스토리지에 업로드합니다. 이 패턴은 의도적으로 지루하게 작성했습니다. requests와 concurrent.futures만 사용합니다. 재미있는 부분은 모델이니까요.

import os, time, io, requests, concurrent.futures as cf
from PIL import Image

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


def submit(prompt, size):
    r = requests.post(BASE, headers=H, json={
        "model": "qwen-image-2.0",
        "input": {"prompt": prompt, "size": size},
    }, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]


def wait(task_id, deadline_s=240):
    deadline = time.time() + deadline_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/{task_id}", headers=H, timeout=30)
        d = r.json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {d.get('error')}")
        time.sleep(4)
    raise TimeoutError(f"task {task_id} not done in {deadline_s}s")


def render_one(item):
    slug, prompt, size = item
    task_id = submit(prompt, size)
    url = wait(task_id)
    png = requests.get(url, timeout=60).content
    buf = io.BytesIO()
    Image.open(io.BytesIO(png)).convert("RGB").save(buf, "WEBP", quality=88, method=6)
    return slug, buf.getvalue()


JOBS = [
    ("packshot-rose-water",  "A clear dropper bottle, label 玫瑰精华水…", "2048*2048"),
    ("packshot-tea-canister","A pale grey ceramic tea canister, label 龙井…", "2048*2048"),
    # … 200 more rows from your sheet …
]

with cf.ThreadPoolExecutor(max_workers=6) as pool:
    for slug, webp in pool.map(render_one, JOBS):
        with open(f"out/{slug}.webp", "wb") as f:
            f.write(webp)
        print(f"saved {slug}.webp ({len(webp)} bytes)")

이 코드에 대해 코드만 봐서는 알 수 없는 작은 설명 몇 가지.

• max_workers=6은 우리가 관찰한 스위트 스팟입니다. 8~10이 되면 대기열 깊이가 처리량이 아니라 추가 지연으로 나타나기 시작합니다. 모델 쪽은 계정별로 동시성을 공정하게 분배하는 것으로 보입니다.
• 저장 전에 품질 88로 webp로 변환합니다. 이 엔드포인트가 만드는 2K png는 약 3~4 MB인데 webp는 200~400 KB로 줄고, 제품 페이지 크기에서는 시각적으로 완전히 동일합니다. 전송 비용이 더 싸고, 모델 자체가 이미 많은 텍스처를 인코딩했기 때문에 JPEG는 이런 텍스처를 잘 처리하지 못합니다.
• 임시 URL은 한 번만 다운로드할 수 있습니다. 업로드 단계가 실패하면(S3 장애, 네트워크 흔들림) 다시 렌더링해야 합니다. 같은 작업의 출력을 얻을 두 번째 기회는 없습니다.

이커머스에 적용할 수 있는 여섯 가지 프롬프트 패턴

내부 A/B 비교에서 더 장황한 대안들을 이기고 살아남은 프롬프트 형태들입니다. 중국어 제품 라벨을 쓰는 영어 사용자를 위해 작성했습니다. 가장 흔한 크로스보더 시나리오입니다.

패턴 1 — 중국어 라벨이 있는 단일 제품 스튜디오 컷

기본 제품 이미지입니다. 배경색은 평이한 영어로 지정하고, 라벨 텍스트는 그대로의 중국어로, 폰트 계열은 영어로 지정하며, 광원 하나를 지정합니다.

A pale grey ceramic tea canister on a clean off-white seamless paper background. The label reads 龙井 in bold black serif Chinese with the small English subtitle Longjing Green Tea below. Soft daylight from camera right, gentle elliptical shadow, no other props. Sharp focus on the label, studio product photography, square 1:1 composition.

효과가 있는 두 가지는 “reads X in bold serif Chinese”로, qwen-image-2.0이 의도한 라벨 위치에 배치합니다. 그리고 “sharp focus on the label”로, 모델이 텍스트를 장식이 아니라 초점 대상으로 취급하게 합니다.

패턴 2 — 빈 접시를 중심으로 구성하는 장면 컷

장면 사진은 장면을 먼저 묘사하고 제품을 마지막에 넣으세요. 그 반대가 아닙니다. 모델은 제품보다 장면에서 흔들릴 가능성이 높으므로 장면을 먼저 고정합니다.

A wooden Japanese-style table near a wide window in late-morning daylight. The window casts a soft rectangle of light onto the table. In the center of the table is the pale grey ceramic tea canister from the previous shot, with a small wisp of steam rising from a cup beside it. Loose tea leaves are scattered to the right. Wabi-sabi aesthetic, soft shadows, shallow depth of field with focus on the canister. 16:9 widescreen composition.

테스트 렌더링에서 통에는 龙井 글자가 있고 바로 아래에 영어 Longjing Green Tea가 표시됐습니다. 스튜디오 컷과 같은 라벨 규율입니다. 증기, 흩어진 찻잎, 창문 빛이 모두 묘사대로 나타났습니다.

패턴 3 — 한 번의 렌더링으로 색상 변형 그리드

변형들이 동일한 제품 형상을 공유할 때는 세 번 대신 한 번의 호출로 전체 그리드를 렌더링할 수 있습니다. 더 저렴하고, 각 칸의 조명이 구조적으로 일관됩니다.

Three pairs of low-top canvas sneakers shot from a slight top-down angle, arranged in one horizontal row on a clean light-grey seamless background. From left to right: dusty rose, sage green, ivory cream. Identical sneaker silhouette, identical lighting, identical shadow. Each pair faces the camera with toes pointing forward. Studio product photography, 1:1 composition, evenly spaced.

이 패턴을 쓰면 각 변형을 따로 렌더링한 뒤 후작업에서 조명을 맞출 필요가 없습니다. “identical sneaker silhouette, identical lighting, identical shadow”라는 제약이 전체 줄을 통일되게 유지하는 핵심입니다.

패턴 4 — 이중 언어 프로모션 배너

Shopee, Lazada, 타오바오의 공동 브랜드 캠페인에서는 보통 같은 이미지에 중국어 제목과 영어 부제를 함께 넣어야 합니다. qwen-image-2.0은 hiapi에서 한 번의 렌더링으로 둘 다 제대로 처리하는 유일한 모델입니다.

A horizontal ecommerce promotional banner on a soft pink gradient background. The main headline reads 双十一大促 in large bold black sans-serif Chinese in the center-left. Below the Chinese headline in smaller dark grey English serif: Double 11 Sale — Up to 50% Off. To the right is a clear glass dropper bottle of pink serum with a small white label. Subtle confetti texture in the background, clean and modern, 16:9 widescreen.

이걸 안정적으로 만들려면 중국어를 프롬프트 가장 앞에 두고 “large bold” 한정사를 붙인 뒤, 영어에 “smaller” 한정사를 붙이세요. 순서를 바꾸면 모델이 영어도 제목 크기로 만드는 경우가 많습니다. 배너 내부의 제품 라벨은 완화해도 되는 부분입니다. 테스트 렌더링에서 qwen은 글자를 명시하지 않아 병에 일반적인 “Vitamin C Serum” 라벨을 선택했습니다. 브랜드 캠페인이라면 리터럴 라벨 텍스트를 프롬프트에 포함시키거나 후반에 실제 라벨을 합성하세요.

패턴 5 — 크로스보더 마켓 리스팅 카드

아마존이나 티몰 리스팅 타일처럼 보이는 복합 소재(제품, 제목, 가격, 배지)는 프롬프트가 사진 브리프가 아니라 레이아웃 브리프처럼 읽혀야 합니다.

A square ecommerce listing card on a white background. In the top two-thirds, a clear glass dropper bottle of pink rose-essence water labeled 玫瑰精华水 / Rose Essence Water. In the bottom third, on the left, the price 99 元 in large bold black Chinese characters with a small English subtitle Rose Essence 30ml below. On the right, a small green badge that reads 新品 in white. Clean modern layout, soft drop shadow under the product, 4:3 composition.

리스팅에는 1:1이 아니라 4:3(2368*1728)으로 렌더링하세요. 대부분 마켓 리스팅 컴포넌트의 메인 비주얼 슬롯은 4:3이라 정사각형을 쓰면 어색하게 잘립니다.

패턴 6 — 개인화를 위한 온디맨드 생성

마지막 패턴은 단위 경제성을 바꿉니다. 렌더링 한 번이 3센트 아래로 내려가면 캠페인용 배너를 미리 렌더링하지 않고 요청 시 고객별로 렌더링할 수 있습니다. “王女士님,月간 구성이 준비되었습니다”처럼 고객의 실제 이름을 배너에 구워 넣는 것입니다. 이름 해시로 캐시하고 TTL을 설정하면 아주 작은 CDN 청구서로 개인화 배너 이미지를 얻을 수 있습니다.

제약은 지연입니다. 렌더링당 25~45초는 동기 요청 흐름에는 너무 느리지만 이메일 발송이나 푸시 알림에는 전혀 문제없습니다. 대기열에 넣을 때 생성하고 메시지가 나갈 때 임베드하면 됩니다.

qwen-image-2.0이 잘하지 못하는 것

균형을 위해 다음 네 가지 작업은 여전히 같은 /v1/tasks 엔드포인트의 다른 모델에 맡깁니다.

• 모션 블러가 있는 핸드헬드 촬영. 스튜디오 컷은 스위트 스팟입니다. 연출되지 않은 느낌(UGC 스타일, 약간의 움직임, 불완전한 구도)이 필요하면 “캐주얼” 구도를 더 잘 이해하는 nano-banana-pro를 시도하세요.
• 픽셀 단위로 일관된 제품 변형. qwen-image-2.0은 호출 간에 유사한 변형을 렌더링하지만, 다섯 가지 조명 설정에서 완전히 동일한 스포이트 병이 필요하다면 참조 이미지 조건화를 지원하는 모델이 필요합니다. hiapi의 어떤 순수 텍스트-투-이미지 모델도 호출 간 픽셀 일관성을 보장하지 않습니다.
• 전신 사진처럼 사실적인 얼굴. 클로즈업 얼굴은 괜찮지만 전신이나 단체 사진은 얼굴 디테일이 부드러워지는 경우가 많습니다. 인물 중심 이커머스(의류 피팅, 뷰티 시연)라면 qwen-image-2.0을 참조 조건화 비디오 모델과 조합해 동작 장면에 활용하세요.
• 1초 미만의 처리 시간. 동기 요청의 내부 루프에서 이미지를 생성해야 한다면(사용자가 화면 앞에서 기다리는 상황) 25~45초는 너무 깁니다. flux-schnell은 약 5초에 이미지당 $0.005로 반환하지만 중국어 텍스트를 렌더링하지 않습니다. 지연 예산을 먼저 기준으로 선택하세요.

200 SKU 신상품 런칭의 실제 비용

대표적인 사례로 엔드투엔드 워크플로의 숫자를 계산해 봅시다.

단계	수량	단가	합계
SKU당 메인 비주얼/스튜디오 컷	200 × 1	$0.025	$5.00
SKU당 장면 컷	200 × 1	$0.025	$5.00
SKU당 변형 그리드(한 번의 렌더링으로 약 3개 변형)	200 × 1	$0.025	$5.00
카테고리당 이중 언어 배너(10개 카테고리)	10 × 1	$0.025	$0.25
SKU당 리스팅 카드	200 × 1	$0.025	$5.00
이미지 생성 총비용	810회 렌더링	—	$20.25

현재 hiapi 가격 기준으로 200 SKU 크로스보더 출시의 전체 이미지 예산은 약 $20입니다. 같은 작업을 고품질 모델(이미지당 $0.04부터)로 하면 $30~$140이고 이미지당 실행 시간도 더 깁니다. 이것이 qwen-image-2.0이 채우려는 격차입니다. 렌더링 횟수를 더 이상 세지 않아도 될 만큼 낮은 비용 구간의 중국어 인식 이커머스 작업입니다.

다음 단계

• qwen-image-2.0 프롬프트 레시피를 읽고 이커머스 전용이 아닌 스타일 중심의 여섯 가지 레시피를 확인하세요.
• hiapi 가격 페이지를 모든 비용 수치의 사실 출처로 삼으세요. qwen-image-2.0은 현재 이미지당 $0.025이지만 그 페이지가 기준입니다.
• 중국어 텍스트가 필요 없는 지연 민감 흐름에는 flux-schnell로 전환하고 동일한 /v1/tasks 형태를 유지하세요. 비교는 FLUX.1 schnell로 이커머스 제품 이미지 생성하기를 참고하세요.

통합 /v1/tasks 엔드포인트의 요점은 모델 전환이 문자열 하나를 바꾸는 일이라는 것입니다. qwen-image-2.0용 루프를 한 번 만들어 두면, 같은 Python 스크립트에서 "model" 필드를 수정하고 해당 모델의 size 스키마에 맞추기만 하면 hiapi의 어떤 이미지 모델로도 렌더링할 수 있습니다.