gpt-image-2.5-flare를 활용한 이커머스 제품 이미지: hiapi API 기반 배치 워크플로

제품 사진 촬영은 보통 상품 카탈로그 등록에서 가장 느린 단계입니다. SKU마다 스튜디오 촬영을 한 번씩 해야 하고, 계절별 배경마다 다시 찍어야 하며, 플랫폼마다 다른 가로세로 비율 규칙에 맞춰 또 한 번 찍어야 합니다. hiapi의 gpt-image-2.5-flare는 이 작업의 대부분을 하나의 모델 ID로 압축합니다. 텍스트 프롬프트로 제품 이미지를 생성할 수도 있고, 기존 사진을 편집할 수도 있습니다(배경 교체, 라이프스타일 장면 연출, 채널별 크기 조정). 제품 자체는 건드리지 않고 말이죠. 이 가이드에서는 세 가지 실제 워크플로와 편집되지 않은 API 출력으로 시연한 뒤, 한 번에 한 장이 아니라 전체 상품 카탈로그에 이를 일괄 적용하는 방법을 보여줍니다.

아래 이미지에 표시된 제품(‘MOSS’라고 적힌 녹색 유리병과 ‘AER’라고 적힌 코발트 블루 주전자)은 이 기법을 시연하기 위한 개념 소품이며 실제 고객 촬영물이 아닙니다. 하지만 모든 이미지는 모의 이미지가 아니라 hiapi API의 실제, 편집되지 않은 출력입니다.

왜 핵심은 하나의 모델 ID인가

gpt-image-2.5-flare는 전달하는 내용에 따라 두 가지 다른 작업을 처리합니다.

• image_urls를 생략하면 텍스트 프롬프트만으로 이미지를 생성합니다(텍스트-이미지).
• image_urls를 추가하면 대신 제공된 사진을 편집합니다(이미지-이미지). 동일한 모델, 동일한 엔드포인트, 동일한 가격입니다.

상품 카탈로그 관점에서 이는 생각보다 중요합니다. 제품을 처음 촬영하든 기존 사진을 재사용하든 두 개의 모델 ID나 두 가지 가격 체계를 오갈 필요가 없습니다. 또한 배치 처리에 특히 적합한 두 가지 세부 사항이 더 있습니다.

• 고정 비용이 아닌 품질 등급. 요청별로 low / medium / high / xhigh / max를 선택할 수 있으므로, 500개 SKU의 썸네일 배치와 홈페이지용 대표 이미지 열 몇 장이 동일한 장당 비용으로 청구될 필요가 없습니다.
• 유연한 가로세로 비율. 요청마다 1:1, 4:5, 9:16, 16:9 등의 비율을 선택할 수 있으므로, 동일한 제품 이미지를 다시 촬영하지 않고도 정사각형 마켓 그리드, 세로형 모바일 피드 또는 와이드 배너로 잘라낼 수 있습니다.

모든 호출은 hiapi의 비동기 작업 API를 통해 이루어집니다. POST /v1/tasks로 작업을 제출한 다음, 상태가 success가 될 때까지 GET /v1/tasks/{id}를 폴링합니다(또는 콜백 사용). 응답에서 바로 이미지를 반환하는 동기 호출은 없습니다. 생성과 편집 모두 몇 초가 걸립니다.

1단계: 처음부터 깔끔한 스튜디오 컷 생성

단순하고 조명이 잘 갖춰진 스튜디오 사진부터 시작하세요. 이것이 이후 단계에서 편집할 기반 소재가 됩니다.

import os
import time
import requests

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


def create_task(prompt, quality="medium", aspect_ratio="1:1", image_urls=None, idempotency_key=None):
    payload = {"model": "gpt-image-2.5-flare",
               "input": {"prompt": prompt, "quality": quality, "aspect_ratio": aspect_ratio}}
    if image_urls:
        payload["input"]["image_urls"] = image_urls
    headers = dict(HEADERS)
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    resp = requests.post(BASE, headers=headers, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id, timeout_s=300, poll_every=5):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]  # download or re-upload immediately — it expires
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


studio_shot_url = wait_for_task(create_task(
    "Photorealistic square studio product photograph. Center exactly one translucent forest-green "
    "glass perfume bottle with a brushed silver cylindrical cap on a pale ivory stone pedestal. A "
    "small rectangular cream label reads \"MOSS\" in a thin serif font. Soft diffused studio lighting, "
    "seamless pale warm-gray background, subtle reflection, no props, no text elsewhere in frame.",
    quality="medium",
    aspect_ratio="1:1",
))

quality="medium"은 첫 처리에 합리적인 기본값입니다. 이 글의 모든 이미지는 동일한 등급을 사용합니다. 추가 디테일이 비용을 상쇄할 가치가 있는 경우에만 개별 SKU를 high로 올리세요(아래 가격 표 참조).

2단계: 제품을 재생성하지 않고 배경 재디자인

여기서부터 카탈로그 작업량이 실제로 줄어드는 워크플로입니다. 스튜디오 컷을 image_urls로 다시 전달하고 원하는 변경 사항만 설명하면, 제품 자체는 픽셀 단위로 동일하게 유지됩니다. 동일한 병 모양, 동일한 뚜껑, 동일한 라벨은 그대로이고 배경만 바뀝니다.

seasonal_variant_url = wait_for_task(create_task(
    "Edit the supplied product photograph. Change ONLY the seamless background from pale warm gray "
    "to muted terracotta orange. Preserve the exact bottle shape and green glass color, the silver "
    "cap, the cream label and all its text, the lighting direction, and the camera angle exactly.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=[studio_shot_url],
))

동일한 패턴이 완전히 다른 제품에도 적용됩니다. 여기서는 코발트 블루 주전자의 배경을 따뜻한 복숭아색 스튜디오 배경천으로 교체했으며, 동일한 방식으로 생성했습니다.

이것이 ‘시즌 리프레시’ 또는 ‘신규 시장 테마’ 작업의 핵심입니다. SKU마다 편집 호출 한 번, 제품은 영향을 받지 않고 배경만 변경됩니다. 500번 실행하면 재촬영 없이 전체 상품 카탈로그에 새 테마를 적용할 수 있습니다.

3단계: 제품을 라이프스타일 장면에 배치

스튜디오 컷은 마켓 그리드 디스플레이에 적합하고, 라이프스타일 장면은 랜딩 페이지나 광고에서 제품을 판매하는 데 효과적입니다. 동일한 편집 패턴에 더 야심찬 프롬프트를 적용하면, 모델이 단순히 배경색만 바꾸는 것이 아니라 정확한 제품을 그럴듯한 실제 장면에 배치합니다.

lifestyle_url = wait_for_task(create_task(
    "Create a photorealistic square lifestyle product photograph using the supplied blue kettle as "
    "the exact product reference. Keep the original cobalt-blue kettle, black handle and base, "
    "brushed-metal spout and lid, black knob, and all lettering completely unchanged. Place it on a "
    "sunlit kitchen countertop with soft natural morning light, a few blurred kitchen props in the "
    "background, shallow depth of field.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=["<your kettle product photo URL>"],
))

모든 편집 프롬프트에 제약 조건 문구(“keep the original ... completely unchanged”)를 유지하세요. 이것이 모델이 주변의 모든 것을 바꾸면서 제품이 변형되는 것을 막아줍니다.

전체 상품 카탈로그를 위한 배치 자동화

단일 편집 호출도 유용하지만, 카탈로그 규모에서는 모든 SKU에 동일한 패턴을 무인으로 실행하는 것이 핵심 가치입니다. 프로덕션 환경에서 효과가 검증된 구조는 다음과 같습니다.

import concurrent.futures
import csv

QUALITY_BY_USE = {"thumbnail": "low", "listing": "medium", "hero": "high"}


def process_row(row):
    idem_key = f"{row['sku']}-{row['use']}-{row['background']}"
    prompt = (
        f"Edit the supplied product photograph. Change ONLY the seamless background to "
        f"{row['background']}. Preserve the exact product shape, color, materials, label text, "
        f"lighting direction, and camera angle."
    )
    try:
        task_id = create_task(
            prompt,
            quality=QUALITY_BY_USE[row["use"]],
            aspect_ratio=row["aspect_ratio"],
            image_urls=[row["source_photo_url"]],
            idempotency_key=idem_key,
        )
        return row["sku"], wait_for_task(task_id)
    except Exception as exc:
        return row["sku"], f"ERROR: {exc}"


with open("catalog.csv") as f:
    rows = list(csv.DictReader(f))  # sku,source_photo_url,background,use,aspect_ratio

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(process_row, rows))

소량 이상의 이미지를 처리할 때는 다음 사항이 중요합니다.

• 행별 멱등성 키. SKU/변형별로 서로 다른 Idempotency-Key 요청 헤더를 보내세요. 그러면 타임아웃 후 재시도된 요청이 중복 작업을 생성하거나 중복 청구하지 않습니다.
• 동시성을 제한하고 한꺼번에 모두 보내지 마세요. 작은 스레드 풀(또는 비동기 세마포어)이 속도 제한에 걸리는 것을 방지합니다. 429를 만나면 이를 하드 실패로 처리하지 말고 백오프 후 재시도하세요.
• 품질 등급은 이미지 용도에 따라 선택하고 일률적으로 적용하지 마세요. 썸네일과 그리드 목록은 보통 low/medium이면 충분하고, 홈페이지 대표 이미지나 광고 크리에이티브에는 high 또는 xhigh가 적절합니다.
• 서로 다른 가로세로 비율은 원본 이미지가 아니라 동일한 편집된 소스 이미지에서 파생시키세요. 먼저 배경 교체 편집을 한 번 실행한 다음, 그 결과에서 1:1, 4:5, 9:16 잘라낸 버전을 요청하여 모든 채널이 완전히 동일한 제품 표현을 보여주도록 하세요.
• 출력 URL은 즉시 다운로드하거나 다시 업로드하세요. 작업 출력은 만료됩니다. 임시 URL을 영구 이미지 소스로 사용하지 마세요.

가격

gpt-image-2.5-flare는 출력 이미지 수와 품질 등급에 따라 청구되며, 처음부터 생성하든 편집하든 동일한 요금이 적용됩니다.

품질	장당 가격
low	$0.0172
medium	$0.0672
high	$0.1829
xhigh	$0.3572
auto	$0.3572
max	$0.7143

medium 등급에서 500개 SKU 카탈로그의 테마를 재디자인하고 제품당 한 번 배경 교체 편집을 실행하는 비용은 약 $33.60입니다. 모든 모델의 최신 전체 요금표는 가격 페이지를 확인하세요.

자주 묻는 질문

편집이 제품을 의도치 않게 바꾸나요? 편집 프롬프트를 단일 변경(“배경만 변경…”)으로 제한하고, 반드시 유지해야 할 항목(모양, 색상, 라벨 텍스트, 카메라 각도)을 명확히 나열하세요. 위 예시는 각 편집에서 제품이 그대로 유지됨을 보여줍니다.

하나의 모델로 생성과 편집이 모두 가능한가요? 네. gpt-image-2.5-flare는 하나의 모델 ID입니다. image_urls를 포함하면 기존 사진을 편집하고, 생략하면 프롬프트만으로 생성합니다.

한 번의 편집 호출에 소스 이미지를 몇 장까지 전달할 수 있나요? image_urls를 통해 최대 16장까지 전달할 수 있지만, 대부분의 상품 카탈로그 편집에는 한 장, 즉 재디자인하려는 사진만 있으면 됩니다.

재시도 시 중복 청구를 어떻게 피하나요? 요청마다 고유한 Idempotency-Key 요청 헤더를 보내세요. 동일한 키로 재시도한 요청은 새 작업을 생성하지 않고 원래 작업을 반환합니다.

관련 읽기

첫 호출을 설정하는 중이라면 gpt-image-2.5-flare API 가이드에서 최소 작업 예제와 비동기 작업 생명주기에 대한 더 깊은 내용을 시작하세요. 제품 사진 외의 더 많은 프롬프트 패턴은 GPT Image 2.5 Flare 프롬프트: 실제 출력이 포함된 복사-붙여넣기 레시피를 참조하세요. 전체 파라미터와 스키마는 모델 페이지에서, 공통 API 규약(인증, 작업 폴링, 콜백)은 hiapi 문서에서 확인하세요.

자신의 상품 카탈로그에서 시도해 볼 준비가 되셨나요? hiapi 대시보드에서 API 키를 받은 다음, 첫 제품 사진에 위의 스튜디오 컷 예제를 실행해 보세요.