튜토리얼

API로 정확한 크기의 제품 이미지 생성하기: 종횡비와 이커머스 플랫폼 규격

Jul 9, 2026

모든 판매 채널은 제품 이미지에 서로 다른 크기를 요구합니다. Amazon은 흰색 배경의 큰 정사각형 이미지를 원하고, Instagram은 4:5 세로 구도를 원하며, Pinterest는 2:3 핀 이미지를, 그리고 자체 스토어 홈페이지의 히어로 비주얼에는 초광폭 이미지가 필요합니다. 이 가이드에서는 hiapi API로 이 모든 크기의 이미지를 프로그래밍 방식으로 생성하는 방법을 소개합니다——gpt-image-2와 wan2.7-image를 사용하여——그리고 매번 목표 픽셀 크기에 정확히 맞추는 방법도 다룹니다.

사전 준비 사항: hiapi API 키(콘솔에서 생성)와 curl 또는 Python. 총 비용은 선택한 모델과 해상도에 따라 달라집니다——가격을 참고하세요.

API에서 이미지 크기가 실제로 작동하는 방식

가장 혼란스러운 점부터 짚고 넘어가겠습니다: hiapi의 이미지 모델은 픽셀 크기를 받지 않습니다. size, width, height 필드가 없습니다. 만약 전달하려고 하면 API가 명확하게 알려줍니다:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'size' not allowed"
}

대신 크기는 input의 두 필드로 제어합니다:

aspect_ratio —— 화면의 형태로, 각 모델마다 고정된 목록에서 선택합니다.
resolution —— 출력 등급: "1K", "2K", "4K"(긴 변이 대략 1024 / 2048 / 4096 픽셀이며, 정확한 픽셀 수는 비율에 따라 다르므로 받은 파일을 반드시 확인하세요).

다음은 이 가이드의 두 모델이 실제로 허용하는 파라미터입니다(라이브 API에서 검증됨):

	`gpt-image-2`	`wan2.7-image/text-to-image`
`prompt`	필수	필수
`aspect_ratio`	`auto`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `3:1`, `1:3`, `21:9`, `9:21` —— 총 16개 값	`1:1`, `16:9`, `4:3`, `21:9`, `3:4`, `9:16`, `8:1`, `1:8` —— 총 8개 값
`resolution`	`1K`, `2K`, `4K`	`1K`, `2K`, `4K`
추가 기능	이미지-투-이미지 변형(`gpt-image-2/image-to-image`)	재현용 `seed`(정수)
픽셀 `size` / `n`	허용 안 함	허용 안 함

실질적인 차이는 다음과 같습니다: gpt-image-2는 소셜 및 이커머스 플랫폼 포맷에 필요한 비율을 모두 포함하며(4:5, 2:3, 5:4는 gpt-image-2 전용), wan2.7-image는 8:1/1:8 초광폭 배너를 추가로 지원합니다——다른 비율 목록에는 없는 비율로, 좁은 띠형 프로모션 배너에 적합하며 4K 스튜디오 촬영 이미지의 일반적인 선택이기도 합니다.

따라서 크기를 정확히 제어하려면 두 단계로 진행합니다:

일치하는 종횡비로 생성하고, 긴 변이 목표 크기 이상인 가장 작은 해상도 등급을 선택합니다(이후 축소만 하고, 절대 확대하지 않음).
반환된 파일을 로컬에서 정확한 목표 픽셀로 조정합니다——Pillow 한 줄이면 됩니다.

이커머스 플랫폼 규격 치트시트

다음은 공개된 일반적인 요구 사항을 API 파라미터에 매핑한 것입니다:

채널	일반적인 목표	`aspect_ratio`	`resolution`	모델 비고
Amazon 메인 이미지	긴 변 ≥1000 픽셀(1600 픽셀 이상이면 줌 활성화), 정사각형, 순백색 배경	`1:1`	`2K`	둘 다 가능
Shopify 제품 페이지	2048×2048 권장	`1:1`	`2K`	둘 다 가능
Instagram 피드(세로 구도)	1080×1350	`4:5`	`2K`	gpt-image-2 전용
Stories / Reels / TikTok	1080×1920	`9:16`	`2K`	둘 다 가능
Pinterest 핀	1000×1500	`2:3`	`2K`	gpt-image-2 전용
Etsy 상품 등록	2700×2025 권장	`4:3`	`4K`	둘 다 가능(4K 등급 필요)
웹사이트 히어로 배너	예: 너비 2560 픽셀	`21:9`	`4K`	둘 다 가능
좁은 띠형 프로모션 배너	초광폭	`8:1`	`2K`/`4K`	wan2.7-image 전용

(플랫폼별 규격은 변경될 수 있으므로, 이 픽셀 목표는 일반적인 공개 권장값으로 간주하고 각 플랫폼의 최신 문서로 확인하세요.)

최소 실행 예제(curl)

모든 것은 통합 비동기 작업 엔드포인트를 통해 실행됩니다: POST /v1/tasks로 생성하고 GET /v1/tasks/<id>로 폴링합니다. 2K 등급을 사용하여 Amazon 스타일의 정사각형 이미지를 생성해 보겠습니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "Studio product photo of a stainless steel water bottle on a pure white background, centered, soft shadow, e-commerce catalog style",
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

응답에서 작업 id는 data.taskId에 있습니다. 이를 폴링합니다:

curl -s https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status가 "success"가 될 때까지(또는 "fail"이 되면 data.error 아래의 상세 정보를 확인) 폴링합니다. 이미지 URL은 data.output[0].url에 있습니다. 해당 URL은 만료됩니다(출력 객체에 expireAt이 포함됨). 따라서 즉시 다운로드하여 자체 스토리지에 다시 호스팅해야 합니다——상품 목록에서 직접 핫링크하지 마세요.

프로덕션 스크립트: 하나의 제품, 모든 채널, 정확한 픽셀

이 배치 스크립트는 모든 작업을 미리 생성하고(플랫폼에서 병렬로 실행됨), 하나씩 완료될 때까지 폴링한 다음, Pillow로 정확한 목표 크기로 조정합니다. ImageOps.fit은 한 번의 호출로 축소와 미세한 크롭을 모두 처리합니다.

import os
import time
from io import BytesIO

import requests
from PIL import Image, ImageOps

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

# 채널 -> 생성 파라미터 + 정확한 픽셀 목표
SPECS = {
    "amazon-main":    {"model": "gpt-image-2/text-to-image", "aspect_ratio": "1:1",  "resolution": "2K", "px": (1600, 1600)},
    "shopify":        {"model": "gpt-image-2/text-to-image", "aspect_ratio": "1:1",  "resolution": "2K", "px": (2048, 2048)},
    "instagram-feed": {"model": "gpt-image-2/text-to-image", "aspect_ratio": "4:5",  "resolution": "2K", "px": (1080, 1350)},
    "story-reel":     {"model": "gpt-image-2/text-to-image", "aspect_ratio": "9:16", "resolution": "2K", "px": (1080, 1920)},
    "pinterest-pin":  {"model": "gpt-image-2/text-to-image", "aspect_ratio": "2:3",  "resolution": "2K", "px": (1000, 1500)},
    "etsy-listing":   {"model": "wan2.7-image/text-to-image", "aspect_ratio": "4:3",  "resolution": "4K", "px": (2700, 2025)},
    "hero-banner":    {"model": "wan2.7-image/text-to-image", "aspect_ratio": "21:9", "resolution": "4K", "px": (2560, 1097)},
}

PROMPT = (
    "Studio product photo of a stainless steel water bottle on a pure white "
    "background, centered, soft shadow, high detail, e-commerce catalog style"
)


def create_task(model: str, prompt: str, aspect_ratio: str, resolution: str) -> str:
    body = {
        "model": model,
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
    }
    data = requests.post(f"{API}/tasks", json=body, headers=HDRS, timeout=60).json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id


def wait_task(task_id: str, timeout_s: int = 600) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        data = requests.get(f"{API}/tasks/{task_id}", headers=HDRS, timeout=30).json()
        task = data.get("data") or {}
        if task.get("status") == "success":
            return task["output"][0]["url"]
        if task.get("status") == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task {task_id} failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


def save_exact(url: str, px: tuple, path: str) -> None:
    # 출력 URL은 만료됩니다 —— 즉시 다운로드한 뒤 정확한 픽셀로 맞춥니다.
    raw = requests.get(url, timeout=120).content
    img = Image.open(BytesIO(raw))
    ImageOps.fit(img, px, Image.LANCZOS).save(path)


if __name__ == "__main__":
    # 먼저 모든 작업을 생성합니다: 작업은 플랫폼에서 동시에 실행됩니다
    tasks = {
        name: create_task(s["model"], PROMPT, s["aspect_ratio"], s["resolution"])
        for name, s in SPECS.items()
    }
    for name, task_id in tasks.items():
        url = wait_task(task_id)
        save_exact(url, SPECS[name]["px"], f"{name}.png")
        print(f"{name}: {SPECS[name]['px']} -> {name}.png")

나머지 부분을 다시 작성하더라도 그대로 따라 할 만한 두 가지 세부 사항이 있습니다:

해상도 등급을 선택할 때 긴 변이 목표 이상이 되도록 하세요. Etsy의 2700 픽셀 목표는 2K 등급의 약 2048 픽셀을 초과하므로 4K로 생성한 뒤 축소합니다. LANCZOS 축소는 카탈로그 용도에서 시각적으로 무손실이지만, 확대는 그렇지 않습니다.
작업 생성 직후 taskId를 영구 저장하세요. 워커가 크래시하면 복구 시 저장된 id를 폴링하고 작업을 다시 생성하지 마세요——다시 생성하면 두 번째 이미지가 생성(및 과금)됩니다.

검수된 메인 이미지를 재구성하는 방법

많은 경우 일곱 장의 독립적으로 생성된 이미지가 아니라, 동일한 검수된 제품 이미지를 각 채널에 맞게 재구성하고 싶을 것입니다. 바로 gpt-image-2/image-to-image가 그 역할을 합니다: input_urls(공개적으로 접근 가능한 이미지 URL 배열)와 prompt가 필요하며, 동일한 16개의 aspect_ratio 값을 받습니다:

{
  "model": "gpt-image-2/image-to-image",
  "input": {
    "prompt": "Extend the background naturally to fill the new frame; keep the product unchanged and centered",
    "input_urls": ["https://your-cdn.com/hero-shot.png"],
    "aspect_ratio": "9:16"
  }
}

동일한 작업 라이프사이클을 따르며, 마지막에 같은 정확한 픽셀 단계를 거칩니다. 전체 과정은 How to Use gpt-image-2 Image-to-Image via the hiapi API에서 확인하세요.

프로덕션 주의 사항

폴링 대신 콜백을 사용하세요. 서버 측에서는 작업 생성 시 최상위 callback을 전달하여 폴링 루프를 완전히 건너뛸 수 있습니다:

{
  "model": "gpt-image-2/text-to-image",
  "input": {"prompt": "...", "aspect_ratio": "1:1", "resolution": "2K"},
  "callback": {"url": "https://yourapp.com/hooks/hiapi", "when": "final"}
}

최종 상태에서 POST를 한 번 받게 됩니다. 콜백은 신호로 취급하고 사실의 출처로 삼지 마세요: 행동하기 전에 GET /v1/tasks/<id>로 다시 가져오고 taskId로 중복 제거하세요. 콜백이 끝내 도착하지 않으면 Why your hiapi task callback isn't firing을 참고하세요.

오류 처리. 인증 실패는 401 permission_denied를 반환합니다——먼저 Authorization: Bearer sk-... 헤더를 확인하세요. 검증 실패는 400과 함께 error_code: "INVALID_REQUEST"를 반환하며, 그 메시지가 특히 유용합니다: 허용되는 정확한 값을 나열해 줍니다(위의 비율 표도 이렇게 검증되었습니다). 입력 스키마는 모델마다 다릅니다——wan2.7-image는 seed를 받지만 gpt-image-2는 받지 않으며, 일부 빠른 모델은 resolution을 완전히 거부합니다——따라서 필드를 하드코딩하기 전에 각 모델의 페이지를 확인하세요.

비용 관리. 가격은 모델과 해상도 등급에 따라 달라집니다. 프롬프트를 반복할 때는 1K로 생성하고, 최종본을 낼 때만 2K/4K로 전환하세요——현재 이미지당 가격은 가격 페이지에서 확인할 수 있습니다.

gpt-image-2 텍스트-투-이미지 모델 페이지 · wan2.7-image 텍스트-투-이미지 모델 페이지
How to use gpt-image-2/text-to-image via the hiapi API —— 전체 파라미터 실습
Wan 2.7 Text-to-Image for E-Commerce Product Photos: 4K Studio Shots
Best AI Image Generation APIs in 2026 —— 아직 모델을 고르는 중이라면 모델 비교를 참고하세요

자주 묻는 질문

요청에 1080×1350 같은 정확한 픽셀 크기를 전달할 수 있나요? 아니요. size, width, height는 400으로 거부됩니다(additional properties ... not allowed). 일치하는 aspect_ratio와 목표 이상의 resolution 등급으로 생성한 뒤, 로컬에서 정확한 픽셀로 축소하세요——위의 Pillow 한 줄 코드가 그것입니다.

Amazon 메인 이미지에는 어떤 설정을 써야 하나요? aspect_ratio: "1:1", resolution: "2K"로 설정한 뒤 목표 크기로 조정하세요(1600×1600이 안정적인 기본값입니다——1000 픽셀 줌 임계값보다 높음). Amazon 메인 이미지는 순백색 배경도 요구하므로 프롬프트에 이를 포함하고, 등록 전에 출력을 검수하세요.

목표 비율이 목록에 없으면(예: 1.91:1 링크 광고 포맷) 어떻게 하나요? 대상을 완전히 포함하는 가장 가까운 더 넓거나 같은 비율로 생성하세요——1.91:1의 경우 2:1 또는 16:9를 사용할 수 있습니다——그런 다음 중앙에서 크롭하세요. 스크립트의 ImageOps.fit이 바로 이렇게 동작합니다: 한 번의 호출로 초과 부분 크롭과 크기 조정을 완료합니다.

진정한 4K 제품 이미지를 얻으려면 어떻게 하나요? 두 모델 모두에서 resolution: "4K"를 설정하세요. wan2.7-image는 4K 스튜디오 스타일 이미지의 일반적인 선택입니다. 프롬프트 패턴은 Wan 2.7 이커머스 가이드를 참고하세요.

생성된 이미지 URL이 만료되나요? 네——모든 출력에는 expireAt이 포함됩니다. 작업이 성공하면 즉시 파일을 다운로드하여 자체 스토리지에 다시 호스팅하세요. 작업 출력 URL을 상품 목록에 붙여넣지 마세요.

한 번의 요청으로 여러 변형을 생성할 수 있나요? 아니요——이 모델들은 n 파라미터가 없습니다. 이미지마다 하나의 작업을 생성하세요. 작업은 동시에 실행되므로 루프에서 배치 처리(위 스크립트처럼)하면 실제 속도는 동일합니다. wan2.7-image에서는 seed를 바꾸어 동일한 프롬프트의 통제된 변형을 얻을 수 있습니다.