사용 가이드

hiapi API로 grok-imagine/text-to-image를 사용하여 이커머스 제품 이미지 생성하기

Aug 5, 2026

대부분의 제품 이미지 파이프라인은 다음 요구 사항을 만나면 무너집니다. 동일한 사진으로 세 가지 다른 형태를 생성해야 하는 경우입니다. 카탈로그 그리드용 정사각형, 모바일 상품 상세 페이지(PDP)용 세로 자르기, 그리고 홈페이지 히어로 배너용 와이드 포맷입니다. 하나의 히어로 이미지를 다시 자르면 모든 비율에서 잘 어울리는 경우는 드물며, 제품이 잘리거나 어색한 빈 공간이 생깁니다. grok-imagine/text-to-image는 이 문제를 피합니다. 필요한 비율로 기본 생성이 가능하며, 이런 배너 작업을 위해 만들어진 두 가지 와이드 포맷(2:1 및 20:9)을 포함합니다. hiapi API에서 이미지당 $0.03으로 해상도와 무관하게 일관되게 책정됩니다.

이 가이드에서는 실제 요청 구조, 테스트 중 마주친 스키마 함정, 단일 제품 브리프에 대해 전체 샷 목록을 실행하는 배치 생성 스크립트, 그리고 카탈로그 규모를 위한 솔직한 비용 계산을 다룹니다.

가격 포지셔닝

작성 시점 hiapi의 가격 페이지에서 확인한 내용:

모델	이미지당 가격	해상도	종횡비 제어
grok-imagine/text-to-image	일괄 $0.03	1K 또는 2K, 동일 가격	`2:1`, `20:9` 포함 13가지 비율
grok-imagine-quality/text-to-image	$0.07 (1K) / $0.10 (2K)	해상도별 차등 가격	동일한 비율 세트

품질 등급은 미세한 디테일—반사, 직물 질감, 작은 텍스트—에서 실제로 눈에 띄는 향상을 제공합니다. 소수의 진정한 핵심 히어로 이미지에는 추가 비용을 지불할 가치가 있습니다. 카탈로그의 대부분 이미지(그리드 썸네일, 라이프스타일 변형, 다른 각도)에는 기본 모델로 충분히 근접하며, 2-3배 가격 차이는 대량 시나리오에서 지불할 가치가 없습니다.

실제로 작동하는 요청

이 페이지의 모든 이미지는 동일한 엔드포인트에서 나왔습니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "matte ceramic pour-over coffee dripper on a pale oak table, soft morning window light from the left, small negative space top-right, no text, no logo, product photography",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }
  }'

이 호출은 taskId를 반환합니다. GET /v1/tasks/{taskId}를 폴링하여 status가 success가 될 때까지 기다린 후 output[0].url을 가져와 다운로드하세요. 해당 URL은 서명되어 있으며 만료되므로 링크를 직접 거는 대신 바이트를 즉시 저장해야 합니다.

테스트 중 세 가지 스키마 세부 사항이 우리를 곤란하게 했으며, 직접 구축하기 전에 알아두면 좋습니다:

aspect_ratio는 자유 형식이 아닌 엄격한 13개 값 열거형입니다. 다른 값을 보내면 전체 목록과 함께 400이 반환됩니다: 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2. 배너에 필요한 두 비율은 2:1과 20:9입니다. hiapi의 대부분 이미지 모델은 최대 21:9까지만 지원하거나 초와이드 옵션을 아예 제공하지 않습니다.
resolution은 소문자만 허용됩니다. "2K"가 아닌 "2k"를 사용하세요. 대문자 형식을 보내면 조용히 변환되지 않고 거부됩니다.
입력 스키마는 엄격합니다. 불필요하거나 잘못 입력된 필드(남아 있는 negative_prompt, 다른 모델 예제에서 복사한 style 키)는 무시되지 않고 전체 요청이 실패합니다.

카탈로그급 깔끔한 이미지를 위한 프롬프트 작성

일관된 카탈로그 출력을 얻는 가장 큰 지렛대는 원하지 않는 것을 명시하는 것입니다. 위의 흰색 배경 히어로 이미지에 효과가 있었던 프롬프트는:

"순수한 흰색 이음새 없는 배경 위의 무광 세라믹 핸드드립 커피 드리퍼, 스튜디오 소프트박스 조명, 중앙 정렬, 부드러운 접촉 그림자 외 그림자 그라데이션 없음, 텍스트 없음, 워터마크 없음, 소품 없음, 이커머스 제품 사진, 선명한 초점"

PDP 보조 이미지나 이메일 배너용 라이프스타일 변형의 경우, 배경과 조명 단서를 바꾸되 동일한 '텍스트 없음 / 워터마크 없음 / 지정된 소품 외 소품 없음' 규율을 유지하세요. 바로 이것이 grok-imagine이 제품 자체에 잡다한 물체나 판독 불가능한 라벨 텍스트를 추가하는 것을 방지합니다:

"같은 세라믹 핸드드립 드리퍼가 나무 주방 조리대 위에 놓여 있고, 옆에 김이 나는 머그가 있음, 따뜻한 아침 빛, 얕은 심도, 아늑한 생활형 주방 배경이 부드럽게 흐려짐, 텍스트 없음, 로고 없음"

초와이드 배너 워크플로

요구 사항이 카탈로그 썸네일이 아닌 홈페이지 또는 카테고리 배너일 때, 2:1과 20:9는 grok-imagine을 특히 채택할 가치가 있게 만드는 두 비율입니다. 요령은 자르기 결과가 우연히 맞기를 바라지 않고 네거티브 공간을 직접 프롬프트하는 것입니다. 제품이 프레임 어디에 있는지, 어떤 영역이 비어 있어야 하는지 설명하세요:

"프레임 오른쪽 3분의 1 지점에 위치한 무광 세라믹 핸드드립 커피 드리퍼, 골든아워 야외 조명, 헤드라인 텍스트 오버레이를 위해 이미지 왼쪽 3분의 2에 걸쳐 충분히 비어 있는 네거티브 공간, 영화 같은 와이드 구성, 텍스트 없음, 로고 없음"

{
  "model": "grok-imagine/text-to-image",
  "input": {
    "prompt": "matte ceramic pour-over coffee dripper positioned in the right third of frame, golden-hour outdoor light, generous empty negative space across the left two-thirds of the image for headline text overlay, cinematic wide composition, no text, no logo",
    "aspect_ratio": "20:9",
    "resolution": "2k"
  }
}

CMS가 비율이 아닌 정확한 픽셀 크기를 요구하는 경우, 가장 가까운 지원 비율로 생성한 다음 해당 이미지에서 무손실 자르기를 하세요. 구체적인 채우기 계산은 API를 통한 정확한 크기 구현 노트를 참고하세요.

전체 샷 목록 배치 생성

단일 제품 브리프에는 보통 하나 이상의 이미지가 필요합니다. 다음 스크립트는 이 페이지의 네 이미지를 생성하는 데 사용한 실제 스크립트를 재현한 것입니다. 이미지마다 하나의 작업을 제출하고, 완료될 때까지 폴링한 다음 디스크에 저장합니다:

import os
import time
import requests

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

SHOTS = [
    {
        "name": "hero",
        "prompt": "matte ceramic pour-over coffee dripper on a pure white seamless "
                  "background, studio softbox lighting, centered, e-commerce product "
                  "photography, no text, no watermark",
        "aspect_ratio": "1:1",
    },
    {
        "name": "lifestyle",
        "prompt": "same ceramic pour-over dripper on a wooden kitchen counter next to "
                  "a steaming mug, warm morning light, shallow depth of field, no text",
        "aspect_ratio": "4:3",
    },
    {
        "name": "banner",
        "prompt": "ceramic pour-over dripper in the right third of frame, soft studio "
                  "light, empty negative space across the left two-thirds for headline "
                  "text, no text, no logo",
        "aspect_ratio": "2:1",
    },
]


def create_task(shot):
    payload = {
        "model": "grok-imagine/text-to-image",
        "input": {"prompt": shot["prompt"], "aspect_ratio": shot["aspect_ratio"], "resolution": "2k"},
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id, poll_interval=5, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


for shot in SHOTS:
    task_id = create_task(shot)
    url = wait_for_result(task_id)
    image_bytes = requests.get(url, timeout=120).content
    with open(f"{shot['name']}.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{shot['name']}: saved {len(image_bytes)} bytes")

전체 다중 SKU 배치를 실행하는 경우, 세 작업을 모두 먼저 제출한 다음 동시에 폴링하세요(작은 asyncio 또는 스레드 풀이면 충분합니다). 각 작업은 보통 1분 이내에 완료되며, 직렬로 실행하면 이유 없이 유휴 대기 시간만 늘어납니다.

실제 카탈로그 운영 비용

이미지당 일괄 $0.03으로 계산하면, 위의 3장 구성(히어로 + 라이프스타일 + 배너)은 SKU당 $0.09입니다. 규모를 키우면:

50 SKU × 3장 = 150장 → $4.50
500 SKU × 3장 = 1,500장 → $45
2K 히어로 이미지만 grok-imagine-quality로 업그레이드하면($0.03 대신 $0.10), 500 SKU 기준 총액은 $80이 됩니다. 이는 기존 방식의 단일 제품 촬영과 비교하면 여전히 푼돈에 불과합니다.

grok-imagine과 나머지 제품 라인 비교

정적 배너가 아닌 이미지가 움직여야 하는 경우—예를 들어 소셜 광고용 6초 제품 모션 클립—동일 제품군은 정적 이미지 중 하나를 시작 프레임으로 사용하는 grok-imagine-image-to-video로 커버됩니다. 해당 워크플로는 숏폼 영상 가이드에서 별도로 다룹니다. Nano-Banana 기반 카탈로그 파이프라인과 비교하는 팀에게는 Nano-Banana 이커머스 가이드가 가장 가까운 나란히 비교 참고 자료입니다. 동일한 작업 API 구조, 다른 모델 강점을 가집니다.

자주 묻는 질문

grok-imagine/text-to-image가 텍스트 프롬프트뿐 아니라 참조 이미지(i2i)도 지원하나요? 지원합니다. 하지만 그것은 별도의 모델 변형(grok-imagine/image-to-image)이며 자체 입력 스키마가 있습니다. 이 가이드는 순수 텍스트-이미지 경로를 다룹니다.

요청이 400과 'additional properties' 오류를 반환하는 이유는 무엇인가요? 입력 스키마는 엄격합니다. prompt, aspect_ratio, 그리고 선택적 resolution만 보냈는지 주의 깊게 확인하세요. 다른 모델 예제에서 복사한 추가 필드를 가져오지 마세요.

열거형에서 선택하는 대신 1200×630 같은 정확한 비율을 얻을 수 있나요? 가장 가까운 지원 비율(16:9는 많은 웹 배너 형태에 가깝습니다)로 생성한 다음 후처리에서 무손실 자르기를 하세요. 구체적인 채우기 방법은 위에 링크된 정확한 크기 가이드를 참고하세요.

2K 해상도는 1K에 비해 기다릴 가치가 있나요? 이 모델은 두 해상도 가격이 동일하므로, 엄격한 지연 예산이 없는 한 기본적으로 2K를 사용하세요. 더 많은 디테일을 무료로 얻습니다.