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

이커머스 상품 카탈로그의 성패는 일관성에 달려 있습니다. SKU가 40개인 판매자는 40번의 서로 다른 촬영이 필요하지 않습니다. 필요한 것은 보기 좋은 배경 하나와, 각 상품을 빠르게 그 안에 넣을 수 있는 방법입니다. 이것이 바로 참조 이미지 기반 이미지 편집의 실제 사용 사례이며, hiapi API의 grok-imagine/image-to-image가 잘하는 일입니다. 장면 하나와 제품 이미지 하나를 주면, 수동 마스크도, 별도의 누끼 단계도 없이 두 가지를 깔끔하고 브랜드에 맞는 이미지로 합성합니다.

이 가이드는 해당 모델의 실제이자 테스트를 거친 요청 스키마(마케팅 문구가 아님), 실제로 청구되는 요금, 전체 상품 카탈로그에 동일한 배경을 적용하는 배치 스크립트, 그리고 각기 다른 크롭 비율을 요구하는 여러 이커머스 플랫폼 간에 출력 종횡비를 제어하는 실용적인 팁을 다룹니다.

이 모델이 실제로 하는 일

grok-imagine/image-to-image는 텍스트 프롬프트 하나와 소수의 참조 이미지를 받아, 이를 하나의 새로운 이미지로 융합합니다. 제품 사진의 경우 이는 다음을 의미합니다:

• 배경 통일 — 모든 SKU 사진을 동일한 스타일의 장면 앞에 배치합니다(테이블, 선반, 스튜디오 배경천). 아무것도 다시 촬영할 필요가 없습니다.
• 장면 합성 — 제품 누끼를 환경 참조 이미지와 결합하여 조명과 구도가 일치하도록 합니다.
• 참조 이미지 간 스타일 전이 — 한 이미지의 색조나 소품을 다른 이미지로 가져오면서 제품 자체는 편집되지 않도록 유지합니다.

이 모든 것이 한 번의 작업 호출로 완료되며, 출력 이미지당 과금에 보낸 참조 이미지당 소액의 요금이 더해집니다.

실제 스키마(가격 페이지가 아닌 라이브 API로 검증)

우리는 grok-imagine/image-to-image로 POST /v1/tasks를 직접 프로빙했으며, 이 모델의 입력 스키마는 정확히 두 개의 필드만 받습니다:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "string, required",
    "image_urls": ["array of public image URLs, required, max 3"]
  }
}

그게 전부입니다. resolution도, aspect_ratio도, strength 파라미터도 없습니다. 페이로드의 다른 어떤 내용이든 엄격한 스키마에 의해 거부됩니다.

지적할 만한 한 가지 정정 사항: hiapi 가격 페이지는 현재 이 모델이 "최대 6장"의 참조 이미지를 지원한다고 주장합니다. 우리는 동일한 요청에 6개와 7개의 이미지 URL을 각각 보내 직접 테스트했고, 둘 다 거부되었습니다:

{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 6, want 3"}
{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 7, want 3"}

이 글을 쓰는 시점에 실제로 적용되는 제한은 호출당 3장의 이미지이며, 6장이 아닙니다. 이 모델을 중심으로 파이프라인을 구축한다면 3장을 기준으로 계획하고, 이와 다른 마케팅 문구는 오래된 내용으로 간주하세요. 해당 제한에 의존하는 자동화를 배포하기 전에 반드시 라이브 POST /v1/tasks 호출로 먼저 확인하세요. 이러한 제한은 플랫폼이 발전함에 따라 바뀔 수 있기 때문입니다.

자동 종횡비: 출력 비율은 첫 번째 참조 이미지를 따릅니다

이 모델에는 aspect_ratio 입력 필드가 없는데, 그렇다면 출력의 형태는 어디서 오는 걸까요? 우리는 동일한 프롬프트, 동일한 두 참조 이미지로 image_urls의 순서만 바꾸는 통제된 테스트를 진행해 답을 찾았습니다.

이 렌더링에서는 제품 사진(백팩)이 image_urls의 첫 번째에 나열되고 그 뒤에 배경 장면이 따라왔습니다. 출력은 1248×832로 반환되었습니다. 제품 사진 자체의 비율과 일치하는 3:2 가로 이미지입니다.

동일한 프롬프트, 동일한 두 이미지이지만 이번에는 배경 장면이 첫 번째에 나열되었습니다. 출력은 1024×1024로 반환되었습니다. 제품이 아닌 장면 참조 이미지 자체의 종횡비와 일치하는 정사각형 크롭입니다.

규칙은 다음과 같습니다: grok-imagine/image-to-image의 출력 종횡비는 image_urls에서 맨 앞에 오는 URL로부터 상속됩니다. 프롬프트에서 구도 힌트("제품 사진" 또는 "와이드 장면")를 읽지 않습니다. 순전히 위치에 기반합니다. 이 점을 알면 실질적으로 유용한 레버가 됩니다. 특정 이커머스 플랫폼이 선호하는 크롭을 얻으려면 참조 이미지 배열을 재배열하기만 하면 됩니다. 인스타그램 스타일의 정사각형 상품 목록에는 정사각형 참조 이미지를 맨 앞에 두고, 와이드 배너 슬롯에는 가로 참조 이미지를 맨 앞에 두세요.

가격(라이브 가격표와 대조하여 확인)

모델	호출 유형	가격
grok-imagine/text-to-image	텍스트 → 이미지	$0.03 / 이미지
grok-imagine/image-to-image	참조 이미지 기반 편집(이 가이드)	$0.03 / 이미지 + 참조 이미지당 $0.003
grok-imagine-quality/text-to-image	텍스트 → 이미지, 프리미엄 티어	$0.07 / 이미지(1K)
grok-imagine-quality/image-to-image	참조 이미지 기반 편집, 프리미엄 티어	$0.08 / 이미지(1K), $0.10 / 이미지(2K), + 참조 이미지당 $0.015

이 가이드에서 사용하는 grok-imagine/image-to-image 기본 티어는 해상도에 따라 달라지지 않는 정액제입니다. -quality 티어처럼 2K/4K 추가 요금을 지불하지 않습니다. 수십 개의 SKU를 동일한 장면에 합성하는 카탈로그 업데이트의 경우, 이미지당 $0.036(제품 사진 1장 + 장면 참조 이미지 1장)이 예산을 책정할 기준 숫자입니다. 대량 실행 전에 반드시 /en/pricing을 다시 확인하세요. 요금은 변경될 수 있습니다.

이미지당 더 선명한 디테일이 필요하고 약 3배의 가격 인상을 감수할 수 있다면, grok-imagine-quality 티어가 동일한 워크플로의 더 높은 충실도 버전입니다. 참조 사진이 전혀 없는 순수 텍스트-이미지 제품 목업의 경우, 기본 티어 텍스트-이미지 워크스루를 참조하세요.

배치 스크립트: 장면 하나, 카탈로그 전체

다음은 재사용 가능한 배경 장면 하나를 받아 폴더의 각 제품 사진과 합성하고, 각각을 독립된 작업으로 제출한 뒤 완료될 때까지 폴링하는 최소한의 Python 루프입니다. 위에서 확인한 스키마를 사용하며 제품 이미지를 첫 번째에 두므로 모든 출력이 제품 사진 자체의 종횡비를 상속합니다. 장면의 비율을 원한다면 순서를 바꾸면 됩니다.

import os
import time
import requests

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

SCENE_URL = "https://static.hiapi.ai/blog/grok-imagine-image-to-image-ecommerce/scene-base.jpg"
PROMPT = (
    "Composite the product from the first reference photo naturally into the "
    "second reference's studio scene, matching its lighting and shadow direction. "
    "Keep the product's shape, color, and texture unchanged."
)


def submit(product_url: str) -> str:
    payload = {
        "model": "grok-imagine/image-to-image",
        "input": {
            "prompt": PROMPT,
            "image_urls": [product_url, SCENE_URL],  # product first -> output follows its ratio
        },
    }
    resp = requests.post(f"{API_BASE}/tasks", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


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


if __name__ == "__main__":
    product_urls = [
        "https://your-storage.example.com/catalog/dripper-raw.jpg",
        "https://your-storage.example.com/catalog/sneaker-raw.jpg",
        "https://your-storage.example.com/catalog/backpack-raw.jpg",
    ]
    for url in product_urls:
        task_id = submit(url)
        output_url = wait_for_result(task_id)
        print(f"{url} -> {output_url}")

프로덕션 파이프라인의 경우 루프에서 폴링하는 대신 작업에 callback.url을 등록하세요. 전체 콜백 페이로드 구조는 hiapi 모델 카탈로그를 참조하세요. taskId를 제품 SKU와 함께 저장하면 실패한 작업을 전체 배치를 다시 제출하지 않고 재시도할 수 있습니다.

실제 제품 사진 예시

이 두 이미지는 모두 동일한 배경 장면 참조 이미지로 생성되었으며, 호출 간에 제품 사진만 교체되었습니다. 조명, 테이블, 배경 식물이 전체 "카탈로그"에 걸쳐 일관되게 유지되는데, 이것이 바로 재사용 가능한 장면 워크플로의 핵심입니다.

자주 묻는 질문

한 번의 호출에 3장 이상의 참조 이미지를 사용할 수 있나요? 아니요. 라이브 스키마는 image_urls에 maxItems: 3을 강제합니다. 이는 직접 API 테스트로 확인된 사실이며, 다른 곳의 마케팅 문구가 무엇을 말하든 마찬가지입니다. 최대 3장의 참조 이미지를 기준으로 프롬프트를 설계하세요(일반적으로 제품 + 장면, 또는 제품 + 장면 + 스타일 참조).

출력의 종횡비를 어떻게 제어하나요? 이 모델에는 aspect_ratio 파라미터가 없습니다. 출력은 image_urls에서 첫 번째 이미지의 종횡비를 상속합니다. 원하는 비율을 얻으려면 참조 이미지를 재배열하세요.

참조 이미지 없는 순수 텍스트 생성도 지원하나요? 아니요. image_urls는 필수 필드입니다. 순수 텍스트 제품 목업의 경우 grok-imagine/text-to-image를 사용하세요. 가격은 $0.03/이미지입니다.

이 모델에 더 높은 충실도 버전이 있나요? 있습니다. grok-imagine-quality/image-to-image는 $0.08/이미지(1K) 또는 $0.10/이미지(2K)에 참조 이미지당 $0.015를 더한 가격으로 동일한 참조 이미지 기반 워크플로를 실행하며 더 선명한 디테일을 제공합니다.

지금 바로 시도해 보세요

hiapi 대시보드에서 API 키를 발급받고, 배경 장면 하나를 준비한 뒤, 전체 카탈로그를 전면 교체할지 결정하기 전에 소수의 SKU로 첫 배치를 실행해 보세요. 이미지당 $0.036으로 계산하면, 10개 제품에 이 워크플로를 테스트하는 비용은 1달러 미만입니다.