hiapi API로 z-image를 사용해 이커머스 상품 이미지 생성하기

대부분의 이미지 모델은 상품을 그릴 수 있습니다. 하지만 상품을 잘 그리면서 동시에 가격을 정확히 표기하는 모델은 훨씬 적습니다. 이커머스 시나리오—가격표, 프로모션 배너, 할인 카드, 패키지 라벨—에서는 이미지 안의 텍스트가 핵심이며, 글자 하나만 깨져도 소재가 반려됩니다.

z-image는 hiapi의 Turbo급 텍스트-투-이미지 모델로, 바로 이 세부 시나리오를 위해 탄생했습니다: 빠른 포토리얼리스틱 이미지 생성, 이미지 내 텍스트(영어 및 중국어) 정확도, 가격은 이미지당 $0.008—대부분의 대안 가격의 3분의 1도 되지 않습니다. 이 가이드의 모든 이미지는 옆에 표시된 것과 완전히 동일한 프롬프트로 생성되었으며, 아래에서 복사할 동일한 /v1/tasks 호출을 통해 완료되었고, 각 렌더링은 엔드투엔드로 약 30–60초가 걸립니다.

상품 이미지에 z-image를 선택하는 이유

이커머스 파이프라인에는 세 가지 중요한 속성이 있으며, z-image는 세 가지 모두에서 뛰어납니다:

• 텍스트 렌더링. 아래 프롬프트 규칙을 따르면 프로모션 카드, 물류 배너, 병 라벨이 모든 단어가 정확히 철자된 상태로 반환됩니다.
• 속도. Turbo 튜닝 모델입니다. 우리의 테스트 렌더링은 매번 1분 훨씬 이내에 완료되어, 수백 개 SKU 이미지의 배치 처리를 커피 한 잔 시간에 끝낼 수 있습니다.
• 가격. $0.008/이미지 기준(가격 페이지에서 확인됨)으로, 1,000개 이미지 카탈로그 갱신 비용은 $8입니다. 동일한 작업을 gpt-image-2($0.03/이미지)로 하면 $30이 듭니다.

모델에 대한 더 포괄적인 개요—키 설정, 일반 예시, 언제 사용하지 말아야 하는지—는 Z-Image API: 가격, API 키, 예시 및 적용 시나리오를 참조하세요. 이 가이드는 이커머스 워크플로에 집중합니다.

검증된 API 인터페이스

z-image는 hiapi의 비동기 작업 엔드포인트에서 실행됩니다. 작업을 제출하고, 성공할 때까지 폴링한 다음, 출력을 다운로드합니다. 우리는 라이브 API를 통해 두 가지 스키마 사실을 확인했습니다(둘 다 플랫폼의 일부 다른 모델과 다릅니다):

1. input은 prompt와 aspect_ratio만 허용합니다. resolution 필드를 보내면 HTTP 400(additional properties not allowed)이 반환됩니다—해당 필드를 요구하는 gpt-image-2와 다릅니다.
2. aspect_ratio는 1:1, 4:3, 3:4, 16:9, 9:16 중 하나여야 합니다. 다른 값(우리는 3:2를 시도했습니다)은 400으로 거부되며 유효 값이 나열됩니다.

출력 해상도는 비율에 따라 고정됩니다—우리의 렌더링 결과는 PNG로 반환되었습니다: 1536×1536(1:1), 1344×768(16:9), 928×1232(3:4), 1728×1296(4:3).

작업 제출

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "Studio e-commerce product photo: a matte black insulated steel water bottle on a seamless light-gray background...",
      "aspect_ratio": "1:1"
    }
  }'

응답에는 작업 id가 포함됩니다:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG"}}

폴링 및 다운로드

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG \
  -H "Authorization: Bearer $HIAPI_API_KEY"

몇 초마다 폴링하여 data.status가 success이고 data.output이 존재할 때까지 기다리세요. fail은 최종 상태로 간주하세요. 실용적인 팁: 생성 직후 작업이 잠시 중간 상태(우리는 archiving을 관찰했습니다)를 보고한 후 output 배열이 나타날 수 있으므로, 루프는 상태 문자열만이 아니라 출력 URL의 존재 여부를 조건으로 해야 합니다.

import os, time, requests

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

def generate(prompt: str, ratio: str = "1:1") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "z-image",
        "input": {"prompt": prompt, "aspect_ratio": ratio},
    }, timeout=60)
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        output = task.get("output") or []
        if output and output[0].get("url"):
            return requests.get(output[0]["url"], timeout=120).content
        if task.get("status") == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...your product prompt...", "1:1")
open("product.png", "wb").write(png)

즉시 다운로드하세요. output[0].url은 expireAt 타임스탬프가 있는 임시 링크입니다—작업 성공 후 즉시 바이트를 자체 스토리지(S3/R2/CDN)에 저장하세요. 작업이 멈춘 것처럼 보이면, 여기에서 hiapi 작업이 멈추거나 시간 초과되는 경우를 진단하는 방법을 소개합니다.

다섯 가지 이커머스 레시피, 실제 출력 포함

아래 모든 이미지는 표시된 것과 완전히 동일한 프롬프트로 생성된 실제 z-image 렌더링 결과입니다. 어떤 보정도 하지 않았습니다.

1. 가격표가 있는 메인 이미지

Studio e-commerce product photo: a matte black insulated steel water bottle centered
on a seamless light-gray background with soft shadow. A rectangular coral paper card
leans against the bottle. The card contains ONLY these two lines of bold clean
sans-serif text and no other words: "SUMMER SALE" on line one, "$19.99" on line two.
Text flat-on to camera, large, perfectly legible. Photorealistic.

표현에 주의하세요: 표시 텍스트는 따옴표 안에 넣고, 프롬프트는 카드가 이 단어들만 포함한다고 말합니다. 첫 번째 시도에서 텍스트를 인라인으로 설명했을 때("...reads exactly: SUMMER SALE on the first line and $19.99 on the second line") 모델은 두 줄 사이에 'ON'이라는 단어를 충실히 조판했습니다—지시 단어가 렌더링 결과로 누출된 것입니다. 리터럴 문자열은 인용하세요; 지시는 따옴표 밖에 두세요.

2. 와이드 프로모션 배너

Wide e-commerce promo banner, photorealistic flat-lay of white sneakers and a kraft
shipping box on a pastel blue background. On the right side, bold navy sans-serif
text with exactly these four words and amount, nothing else: "FREE SHIPPING OVER $50".
All four words must appear. Text large, straight, perfectly legible. Clean commercial
studio lighting.

16:9는 1344×768 배너를 제공하여 상점 홈페이지 메인 비주얼 영역에 바로 넣을 수 있습니다.

3. 소셜 미디어 세로형 할인 카드

Vertical social-media product card: a small brown glass cosmetic dropper bottle on a
warm beige podium, soft daylight. Above the bottle, bold black modern sans-serif
headline text reads exactly: 30% OFF TODAY ONLY. Text flat to camera, large and
perfectly legible. Minimalist premium e-commerce style, photorealistic.

3:4(928×1232)는 피드 게시물 형식에 가장 가까운 비율입니다; 플랫폼에서 요구한다면 다운스트림에서 4:5로 자를 수 있습니다.

4. 읽을 수 있는 패키지 라벨

Macro e-commerce product photo of a frosted glass skincare bottle with a clean white
label. The label text, printed in elegant dark sans-serif, reads exactly: GLOW SERUM
on the first line and VITAMIN C 10% on the second line. Straight-on angle, label
fully visible and sharp, soft studio lighting, photorealistic, white background.

이것은 이 세트에서 가장 어려운 테스트였습니다—곡면 유리 위의 작은 글자—라벨은 '10%'를 포함해 깨끗하게 반환되었습니다.

5. 컬러 라인업 (텍스트 없음)

E-commerce catalog photo: three identical ceramic coffee mugs lined up left to right
in sage green, terracotta orange, and navy blue, on a plain white studio background
with soft even shadows. No text anywhere in the image. Photorealistic, consistent
product geometry across all three mugs.

변형 간의 일관된 형상이 바로 카탈로그 스트립으로 사용할 수 있게 하는 핵심입니다—z-image는 한 번의 생성에서 세 가지 색상 머그의 모양을 동일하게 유지했습니다.

텍스트를 살리는 프롬프트 규칙

실제 실행에서 효과가 있었던(그리고 실패했던) 경험을 응축했습니다:

1. 리터럴 문자열을 따옴표로 묶으세요. text reads exactly: "SUMMER SALE"—모델은 따옴표 없는 주변 단어를 후보 카피로 간주합니다.
2. "and no other words"(그리고 다른 단어 없음)를 추가하세요. 그렇지 않으면 모델이 공간을 채우기 위해 추가 배지 카피를 지어낼 수 있습니다.
3. 텍스트를 카메라에 정면으로 유지하세요. 우리의 유일한 깨진 렌더링은 태그에 비스듬히 걸린 텍스트였습니다; 동일한 카피를 평평한 카드에 넣으면 완벽했습니다. 원근 변형은 글자가 가장 먼저 무너지는 곳입니다.
4. 이미지당 하나 또는 두 개의 텍스트 블록. 텍스트 블록이 하나 추가될 때마다 실패 확률이 배가됩니다; 복잡한 레이아웃은 다운스트림에서 합성하세요.
5. 게시 전에 검증하세요. 이 가격이면 재시도 루프를 감당할 수 있습니다: 렌더링, OCR 또는 육안으로 텍스트 확인, 불일치 시 재생성. 실패한 이미지마다 한 번씩 재시도해도 비용은 대안 모델의 일부에 불과합니다.

배치 비용

구체적인 시나리오: 200개 SKU × 각 3개 소재(상품 목록 이미지, 프로모션 배너, 소셜 카드) = 600개 이미지.

모델	가격/이미지	600개 이미지	비고
z-image	$0.008	$4.80	Turbo 속도, 이미지 내 텍스트 성능 강함
flux-schnell	$0.005	$3.00	가장 저렴하지만 텍스트 렌더링에 중점을 두지 않음
qwen-image-2.0	$0.025	$15.00	범용 품질 강함
gpt-image-2	$0.03	$18.00	resolution 필드 필요; 이커머스 가이드는 여기

(가격은 게시 시점의 hiapi 가격 페이지에서 가져왔습니다.)

배치 모드는 위의 generate() 함수를 루프에 넣는 것입니다—소량의 작업을 동시에 제출하고, 작업 id를 수집한 다음, 그룹으로 폴링하세요. 대량으로 밀어붙이려면 먼저 hiapi가 속도 제한과 버스트 트래픽을 처리하는 방법을 읽어보세요.

시작하기

콘솔에서 API 키를 받은 다음, 위의 코드 조각을 자신의 상품 카탈로그에 연결하세요—z-image 모델 페이지에는 모델 카드가 있고, hiapi 문서는 작업 API를 포괄적으로 소개합니다. 렌더링당 $0.008로, 파이프라인에 적합한지 알아보는 가장 저렴한 방법은 오늘 오후에 가장 까다로운 SKU 열 개로 한 번 실행해 보는 것입니다.