Imagen 4 이커머스 제품 이미지: 프롬프트, 배치 코드 및 품질 검수

개요

• 표준 버전 Imagen 4는 HiAPI에서 imagen-4.0으로 실행되며, 가격은 이미지당 $0.06이고, 요청당 한 장의 이미지를 생성하며 텍스트→이미지 변환만 지원합니다. Imagen 4 모델 페이지 열기에서 먼저 프롬프트를 하나 시험해 볼 수 있습니다.
• 제품 카탈로그의 경우, 흰 배경 제품 이미지와 라이프스타일 이미지를 생성하는 데 적합합니다. 이러한 이미지는 원래 색상 조합마다 별도로 촬영해야 했습니다. 다만 참조 이미지 입력이 없으므로 당신의 실제 SKU를 재현할 수는 없습니다.
• aspect_ratio는 필수 항목이며(기본값 없음), seed는 반드시 숫자 문자열이어야 합니다. 저희 테스트에서 "seed": "sku-dripper-01"은 유효성 검사를 통과했지만 약 1초 후 모든 작업이 TASK_FAILED로 실패했습니다.
• 품질 검수 단계를 반드시 마련하세요. 4장 이미지 배치에서 요청하지 않은 유리 주전자 하나, 무광으로 요청했지만 광택이 나는 유약, negative_prompt: "text, logo"를 설정했음에도 소품의 허위 라벨 텍스트가 나타났습니다.

이 가이드에서 다루는 내용

이것은 온라인 스토어를 위한 실용적인 워크플로로, 하나의 제품 라인에 대한 이미지 세트를 생성합니다: 각 SKU마다 흰 배경 카탈로그 이미지 1장, 제품 페이지용 라이프스타일 이미지 1장, 모바일 스토리용 세로 크롭 이미지 1장입니다. 아래의 모든 내용은 2026-11-04에 라이브 API를 대상으로 실행했으며, 가상 제품(회녹색 도자기 핸드드립 드리퍼와 어울리는 머그)을 사용했습니다.

첫 요청만 성공시키고 싶다면 Imagen 4 API 사용 방법부터 시작하세요. 일반적인 프롬프트 템플릿은 Imagen 4 프롬프트를 참고하세요. 이 가이드는 스토어 이미지 세트를 대량 생성하고 출시 전에 검수하는 방법을 다룹니다.

프롬프트를 작성하기 전에 티어를 선택하세요

HiAPI의 세 가지 Imagen 4 티어는 모두 텍스트→이미지 변환이며 요청 구조가 같습니다: model id만 변경하면 티어가 전환됩니다. 가격은 테스트 당일의 HiAPI 가격에서 가져왔습니다.

티어	모델 id	이미지당 가격	모델 페이지
Fast	imagen-4.0-fast	$0.03	Imagen 4 Fast
Standard	imagen-4.0	$0.06	Imagen 4
Ultra	imagen-4.0-ultra	$0.09	Imagen 4 Ultra

제품 카탈로그의 경우 계산은 간단합니다. 200개 SKU × (제품 이미지 1장 + 라이프스타일 이미지 1장) = 400장의 이미지이며, 표준 티어에서 $24, Fast 티어에서 $12, Ultra 티어에서 $36이며, 재시도는 포함되지 않습니다. 이 글에서는 표준 티어만 테스트했으므로 Fast나 Ultra의 품질에 대해서는 어떠한 주장도 하지 않습니다. 전체 가격 내역은 Imagen 4 API 가격을 참고하세요.

요청: 네 개의 필드, 그중 두 개가 오류가 잦은 지점

imagen-4.0의 입력 스키마는 닫혀 있습니다. 아래는 배치 처리를 구축할 때 저희가 마주친 경계 사례와 정확한 오류 메시지입니다:

필드	규칙	저희가 관찰한 결과
prompt	필수 문자열	—
aspect_ratio	필수, 값은 1:1, 16:9, 9:16, 3:4, 4:3, auto 중 하나	생략: aspect_ratio: missing required field "aspect_ratio". "2:1": value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'
negative_prompt	선택 문자열	수락됨. 소품의 텍스트가 줄었으나 제거되지는 않음(품질 검수 참조)
seed	선택 문자열	숫자(12): seed: got number, want string. 숫자가 아닌 문자열("sku-dripper-01"): HTTP 200으로 수락된 후 작업이 TASK_FAILED로 종료됨. 숫자 문자열("1042"): 정상 작동
그 밖의 모든 것	거부됨	additional properties 'foo' not allowed

seed 문제로 인해 한 라운드를 더 소비했습니다. 재실행 시 추적할 수 있도록 SKU 코드를 seed로 사용하는 것이 유혹적이며, 검증기 또한 이를 통과시켰습니다. 저희 첫 배치의 네 작업 모두 다음과 같은 결과를 반환했습니다:

{"code":200,"data":{"error":{"code":"TASK_FAILED","message":"task failed"},"model":"imagen-4.0","status":"fail"}}

그런 다음 필드를 하나씩 제거했습니다. 동일한 프롬프트에 negative_prompt만 있을 때는 성공했고, "seed": "sku-dripper-01"만 있을 때는 실패했으며, "seed": "1042"일 때는 성공했습니다. seed는 숫자로 유지하고 SKU 매핑은 자체 작업 테이블에 저장하세요.

출력 크기는 비율에 따라 달라집니다. 저희 테스트에서 1:1은 1024×1024, 4:3은 1152×864, 9:16은 720×1280을 반환했으며 모두 WebP입니다. 스토어에 2000px로 확대한 이미지가 필요하다면 업스케일 단계를 계획하세요. 출력 자체는 그렇게 크지 않습니다.

카탈로그 이미지 세트를 위한 프롬프트

제품이 아니라 촬영 유형별로 프롬프트 템플릿을 작성한 다음 제품 설명을 채워 넣으세요. SKU마다 조명, 카메라 각도, 배경을 일관되게 유지해야 제품 그리드가 같은 카탈로그처럼 보입니다.

제품 이미지(1:1). 배경, 구도, 단일 조명 방향, 원하는 그림자를 명시하세요:

Studio packshot of a matte sage-green ceramic coffee mug with a thin loop handle
on a seamless pure white background, centered, handle pointing right, eye-level view,
soft diffused key light from the left, gentle contact shadow, e-commerce catalog photography

머그는 깔끔하게 반환되었습니다: 손잡이는 요청대로 오른쪽을 향했고, 그림자는 부드러웠으며, 배경은 균일했습니다. 편집이 필요 없었습니다.

라이프스타일 이미지(4:3). 주 피사체, 표면, 조명 방향, 그리고 어떤 소품이 초점에서 벗어날지를 지정하세요. 그런 다음 제품이 선명한 주 피사체임을 다시 명시하세요:

Lifestyle product photo: a matte sage-green ceramic pour-over dripper sitting on a glass carafe
on a light oak kitchen counter, morning window light from the right, a bag of coffee beans and a
gooseneck kettle softly out of focus in the background, warm natural tones, shallow depth of field,
the dripper is the sharp hero of the frame

이 프롬프트가 이 글 상단의 이미지를 생성했습니다.

세로 스토리 이미지(9:16). 상단에 제목을 넣을 계획이라면 여백 공간을 명시적으로 요구하세요:

Vertical lifestyle product photo for a mobile story: overhead flat lay of a matte sage-green ceramic
pour-over dripper on a linen napkin, scattered roasted coffee beans, a small ceramic cup of black coffee,
on a pale stone surface, soft even daylight, generous empty space in the top third for a headline

상단 3분의 1의 여백은 요청대로였습니다. 하지만 커피콩 하나가 드리퍼 안에 놓여 있습니다: 커피를 그렇게 내리는 사람은 없으며, 커피 구매자라면 알아차릴 것입니다. 자세한 내용은 아래를 참조하세요.

비동기 배치 처리 코드

HiAPI 이미지 생성은 비동기입니다: POST /v1/tasks가 taskId를 반환하면 GET /v1/tasks/{taskId}를 폴링하여 status가 success 또는 fail이 될 때까지 기다립니다(비동기 API 문서 참조). 제품 카탈로그의 경우 모든 작업을 한 번에 제출하고 병렬로 폴링하세요. 이것은 저희가 실행한 스크립트이며 프롬프트는 간략화했습니다. 두 장의 장면 이미지는 이 스크립트에서 직접 나왔습니다. 두 장의 제품 이미지는 위의 seed 실패를 조사하면서(seed 없는 드리퍼 제품 이미지) 동일한 프롬프트로 한 장씩 생성했습니다.

import os, time, json, concurrent.futures as cf
import requests

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

NEG = "text, logo, watermark, hands, people, clutter, reflections of camera"

JOBS = [
    {"sku": "dripper-white", "aspect_ratio": "1:1", "seed": "1041", "prompt": "Studio packshot of ..."},
    {"sku": "mug-white",     "aspect_ratio": "1:1", "seed": "1042", "prompt": "Studio packshot of ..."},
    {"sku": "dripper-scene", "aspect_ratio": "4:3", "seed": "2041", "prompt": "Lifestyle product photo: ..."},
    {"sku": "dripper-story", "aspect_ratio": "9:16", "seed": "3041", "prompt": "Vertical lifestyle product photo ..."},
]

def submit(job):
    body = {"model": "imagen-4.0",
            "input": {"prompt": job["prompt"], "aspect_ratio": job["aspect_ratio"],
                      "negative_prompt": NEG, "seed": job["seed"]}}  # seed: digits only
    r = requests.post(API, headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        data = r.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(4)
    raise TimeoutError(task_id)

def run(job):
    t0 = time.time()
    task_id = submit(job)
    data = wait(task_id)
    if data["status"] != "success":
        return {"sku": job["sku"], "status": "fail", "error": data.get("error")}
    url = data["output"][0]["url"]
    img = requests.get(url, timeout=60).content
    path = f"{job['sku']}.webp"
    open(path, "wb").write(img)          # download now: output URLs expire
    return {"sku": job["sku"], "status": "success", "task_id": task_id,
            "seconds": round(time.time() - t0, 1), "bytes": len(img), "file": path}

with cf.ThreadPoolExecutor(max_workers=4) as pool:
    for result in pool.map(run, JOBS):
        print(json.dumps(result))

프로덕션 환경에서 중요한 세 가지 세부 사항이 있습니다:

1. 실패한 작업도 HTTP 200을 반환합니다. data.status == "fail"과 data.error.code를 확인하세요. raise_for_status()에만 의존하지 마세요.
2. 즉시 다운로드하세요. output[0].url은 expireAt 타임스탬프가 있는 임시 링크입니다(저희 응답에서는 약 7일 후). 바이트를 자체 스토리지나 CDN에 복사하세요. 스토어에서 해당 URL을 핫링크하지 마세요.
3. SKU 옆에 작업 id를 기록하세요. 검수자가 특정 이미지를 반려했을 때, 이를 생성한 프롬프트, seed, 작업 id를 알아야 합니다.

저희 테스트에서 개별 작업은 서버에서 7–8초 만에 완료되었습니다(created → completed). 병렬로 실행한 두 장면 작업은 4초 폴링 간격과 다운로드를 포함하여 실제 31초와 42초가 걸렸습니다. max_workers=4를 사용하면 소규모 배치에서는 생성 시간보다 폴링 오버헤드가 지배적입니다.

품질 검수: 이미지가 출시되기 전에 확인할 항목

텍스트→이미지 생성은 그럴듯한 제품을 만들어 내며, 창고에 있는 그 제품의 사진을 만드는 것이 아닙니다. 모든 이미지는 실제 SKU와 대조하여 사람 또는 자동으로 확인해야 합니다. 아래는 저희가 4장 이미지 배치에서 발견한 문제입니다:

검사 항목	저희 배치에서의 상황	수정 방법
화면에는 나열된 제품만	드리퍼 제품 이미지에 손잡이가 달린 어울리는 녹색 유리 주전자가 추가로 생겼으며, 프롬프트에는 전혀 요청하지 않았습니다(위 이미지 참조).	"single object, nothing else in frame"을 추가하고 재시도하세요. 판매하지 않는 세트를 절대 게시하지 마세요.
표면 효과와 재질	저희는 "무광" 유약을 요청했습니다. 두 장의 드리퍼 이미지 모두 광택 효과로 반환되었습니다. 머그는 더 새틴에 가까웠습니다.	재질 단어는 힌트로 취급하세요. 실제 제품과 비교하여 일치하지 않으면 반려하세요.
소품의 텍스트	라이프스타일 장면의 커피 봉지에는 negative_prompt: "text, logo"를 설정했음에도 로고 같은 표시와 판독 불가능한 라벨 텍스트가 있었습니다.	라벨이 있는 소품이 프롬프트에 나오지 않게 하거나, 흐리게 처리하거나 크롭하세요. 허위 텍스트가 상품 목록에 들어가게 하지 마세요.
제품 논리	오버헤드 이미지는 커피콩 전체를 드리퍼 안에 넣었습니다.	해당 제품 카테고리를 이해하는 사람이 장면 이미지를 검수하게 하세요.
이미지 간 일관성	드리퍼의 리브 패턴과 바닥 모양이 제품 이미지, 장면 이미지, 오버헤드 이미지 간에 각각 달랐습니다.	실제 제품과 일치하지 않는 한 같은 제품 페이지에 "동일" SKU의 생성 이미지를 혼용하지 마세요.
크기와 비율	모든 출력이 요청한 비율을 따랐습니다(1024², 1152×864, 720×1280).	다운로드 후 픽셀 크기를 자동으로 검사하세요.

마지막 항목은 스토어에 있어 핵심적인 결정입니다. Imagen 4는 카테고리 배너, 라이프스타일 분위기 이미지, 광고 크리에이티브, 그리고 규격으로만 존재하는 제품의 플레이스홀더 이미지에 사용하세요. 정확한 상품을 보여줘야 하는 목록 사진의 경우 실제 제품 사진에서 시작하여 이미지→이미지 모델로 전환하세요. 저희의 Seedream 4.5 이미지→이미지 이커머스 가이드에서 해당 워크플로를 자세히 다룹니다.

자주 묻는 질문

imagen-4.0이 실제 제품을 새 장면에 넣을 수 있나요? 아니요. HiAPI에서는 prompt, aspect_ratio, negative_prompt, seed만 허용합니다. 이미지 입력 필드가 없으므로 제품 사진을 참조로 사용할 수 없습니다.

negative_prompt가 모든 텍스트를 제거하나요? 저희 테스트에서는 아니었습니다. 보내는 것이 좋지만, 라이프스타일 장면의 배경 소품에 여전히 허위 라벨 텍스트가 나타났습니다. 확실한 해결책은 라벨이 있는 소품을 피하는 것입니다.

왜 제 작업이 즉시 TASK_FAILED로 실패하나요? 먼저 seed를 확인하세요. "sku-dripper-01" 같은 숫자가 아닌 문자열은 유효성 검사를 통과하지만, 저희 테스트에서는 모든 작업이 실패했습니다. "1042"처럼 문자열 형태의 숫자를 사용하세요.

Google-Imagen4는 다른 모델인가요? 저희 테스트에서 "model": "Google-Imagen4"로 보낸 요청은 성공했으며, 작업 페이로드는 "model": "imagen-4.0"을 보고했습니다. 새 코드에서는 imagen-4.0을 사용하세요.

다음 단계

제품을 하나 선택하고 위의 세 가지 프롬프트 템플릿을 작성한 다음 Imagen 4 모델을 대상으로 배치 스크립트를 실행하세요. 이를 카탈로그 파이프라인에 연결하려면 비동기 API 문서에서 인증과 폴링을 다룹니다.