제품 정지 이미지로 숏폼 영상 생성: hiapi API의 grok-imagine/image-to-video

숏폼 제품 콘텐츠에는 공급 문제가 존재합니다. 바로 게시 가능한 짧은 영상은 과거에 한 번의 촬영을 의미했습니다. 스튜디오 촬영 시간, 모션 디자인, 편집자까지. 하지만 이미 이커머스 상품 카탈로그를 운영 중이라면, 손에 바로 쓸 수 있는 원재료가 이미 있습니다. 수천 장의 제품 정지 이미지입니다. grok-imagine/image-to-video (xAI의 Grok Imagine 이미지-투-비디오 엔드포인트)는 한 번의 비동기 API 호출로 이 정지 이미지들을 6~30초의 시네마틱 영상으로 바꿔주며, 참조 이미지 조건 제어를 통해 제품이 여전히 당신의 제품처럼 보이도록 합니다.

이 가이드는 hiapi API에서의 엔드투엔드 워크플로우입니다. 단일 카탈로그 정지 이미지를 움직이게 하고, 여러 참조 이미지로 피사체 일관성을 고정하고, 피드 경제성에 맞춰 길이와 해상도 티어를 선택하며, 전체 카탈로그를 세로형 숏폼 영상 큐로 배치 처리하는 방법입니다. 아래에 삽입된 각 영상은 실제 API에서 나온, 편집되지 않은 첫 출력물입니다. 이 글을 위해 우리 소재 라이브러리의 정지 이미지로 생성했으며, 옆에 정확한 프롬프트와 설정을 첨부했습니다.

모델, 제한, 가격

grok-imagine/image-to-video는 hiapi의 비동기 작업 인터페이스(POST /v1/tasks)에서 실행됩니다. 이 글을 위해 실측 검증한 입력 스키마:

• image_urls (배열, 필수) —— 하나 이상의 공개 접근 가능 참조 이미지 URL. 비공개이거나 가져올 수 없는 URL은 스키마 오류가 아니라 정규화 단계에서 실패하므로, 참조 이미지를 먼저 공개 위치에 호스팅하세요.
• prompt (문자열, 선택) —— 운동, 카메라, 분위기 지시. 프롬프트를 제공하지 않으면 모델이 자유롭게 생성합니다. 제품 콘텐츠를 만들 때는 항상 제공해야 합니다.
• duration (정수, 6~30초)
• resolution (480p 또는 720p)
• aspect_ratio (1:1, 2:3, 3:2, 16:9, 9:16)

motion_mode, seed, 네거티브 프롬프트 필드는 없습니다. 알 수 없는 필드는 400으로 거부됩니다. 모든 운동 제어는 프롬프트 문구로 합니다.

이 글을 위해 영상을 생성할 때 겪은 한 가지 동작: aspect_ratio가 참조 이미지 자체의 종횡비와 일치하지 않으면 참조 이미지가 종종 우선합니다. 아래 세 번의 실행 모두 9:16을 요청했습니다. 두 개의 정사각형 소스 정지 이미지는 정사각형 영상(960×960 및 544×544)을 반환했고, 첫 번째 참조 이미지가 가로형이었던 실행은 진정한 720×1280 세로형을 전달했습니다. 피드에 9:16이 보장되어야 한다면, 해당 파라미터에 의존하지 말고 제출 전에 참조 정지 이미지를 9:16으로 자르세요.

가격은 출력 초 단위로 청구되며, 작성 시점의 hiapi 가격 페이지 기준입니다:

티어	초당 가격	6초 영상	15초 영상	30초 영상
480p	$0.0114	$0.068	$0.171	$0.342
720p	$0.0214	$0.128	$0.321	$0.642

이 가격이 전체 워크플로우를 형성합니다. 6초 720p 히어로 영상은 약 13센트이고, 480p 초안은 그 절반 정도입니다. 반복 작업을 충분히 감당할 수 있습니다.

제출 → 폴링 → 다운로드

작업 생애주기는 제출, 폴링, 다운로드입니다. curl로 제출:

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/image-to-video",
    "input": {
      "prompt": "Slow cinematic orbit around the bag, studio lighting glinting off the brass zippers, background stays clean, product unchanged.",
      "image_urls": ["https://your-cdn.example.com/products/weekender.jpg"],
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "9:16"
    }
  }'

즉시 작업 ID를 받습니다:

{"code": 200, "data": {"taskId": "tk-hiapi-01KX2H8WMWQG99A2F97BREDPS6"}, "message": "success"}

그런 다음 GET /v1/tasks/{taskId}를 폴링하여 status가 success가 될 때까지 기다린 후 output[0].url을 다운로드합니다. 아래는 이 글의 모든 영상을 생성하는 데 사용한 정확한 패턴인 완전한 Python 헬퍼 스크립트입니다:

import json, subprocess, time, os

API = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]

def submit(input_fields: dict) -> str:
    payload = {"model": "grok-imagine/image-to-video", "input": input_fields}
    out = subprocess.run(
        ["curl", "-s", "-X", "POST", API,
         "-H", f"Authorization: Bearer {TOKEN}",
         "-H", "Content-Type: application/json",
         "-d", json.dumps(payload)],
        capture_output=True, text=True, timeout=70).stdout
    data = json.loads(out)
    if not (data.get("data") or {}).get("taskId"):
        raise RuntimeError(f"submit failed: {out[:300]}")
    return data["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 1200) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        out = subprocess.run(
            ["curl", "-s", f"{API}/{task_id}",
             "-H", f"Authorization: Bearer {TOKEN}"],
            capture_output=True, text=True, timeout=40).stdout
        task = json.loads(out)["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)
    raise TimeoutError(task_id)

task_id = submit({
    "prompt": "...",
    "image_urls": ["https://your-cdn.example.com/products/weekender.jpg"],
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "9:16",
})
task = wait(task_id)
video_url = task["output"][0]["url"]
subprocess.run(["curl", "-s", "-o", "clip.mp4", video_url], timeout=180)

프로덕션 환경에서 주의할 두 가지 운영 세부 사항:

1. output[0].url은 유효 기간이 있는 서명 링크입니다(만료 시간 포함). 작업이 성공하자마자 즉시 바이트를 다운로드하여 자체 스토리지로 이전하세요. 원본 작업 URL을 영구 저장하지 마세요.
2. 과금은 작업이 수락될 때 발생하므로, 대량 제출 전에 먼저 검증하세요. 유용한 팁: "duration": 99와 같이 범위를 벗어난 값을 보내면 전체 스키마 검증 오류를 받고 과금 가능한 작업은 생성되지 않습니다.

정지 이미지 한 장 → 히어로 영상 하나

가장 일반적인 작업: 카탈로그 제품 이미지를 가져와 연속적인 카메라 운동을 부여합니다. 제품 사진은 본질적으로 정적이므로, 프롬프트의 역할은 신뢰할 수 있는 운동 하나만 추가하고 나머지는 모두 명시적으로 고정하는 것입니다:

Slow cinematic orbit around the burnt-orange canvas weekender bag, camera
circling smoothly from front to three-quarter view, studio lighting glinting
off the brass zippers, seamless white background stays clean and shadowless,
product perfectly sharp and unchanged, subtle premium e-commerce energy.

실제 출력 — grok-imagine/image-to-video, 6초 @ 720p, 단일 참조 이미지. 첫 생성, 편집 없음. 실제 전달은 960×960: 정사각형 소스 정지 이미지가 우리의 9:16 요청을 덮어썼습니다(위 종횡비 설명 참조). 소스 정지 이미지는 아래와 같습니다.

제품 영상을 사실적으로 유지하는 프롬프트 패턴:

• 카메라 동사 하나("궤도", "푸시인", "이동"). 한 프롬프트에 두 개의 운동을 넣으면 멀미나는 화면이 나옵니다.
• "제품 불변 / 완전 선명"을 명시적으로 작성. 이미지-투-비디오 모델은 드리프트합니다. 피사체가 변경될 수 없다고 모델에 알려주면 로고, 스티치, 하드웨어의 변형이 크게 줄어듭니다.
• 소재의 순간을 언급("황동 지퍼 위에 반짝임") — 금속과 가죽 위로 빛이 이동하는 것이 정지 이미지가 왜곡이 아니라 촬영처럼 느껴지게 하는 이유입니다.
• 배경 고정("깨끗하고 그림자 없이 유지"). 그렇지 않으면 모델이 배경을 스스로 발명합니다.

여러 참조 이미지: 피사체 고정

image_urls는 한 장 이상의 참조 이미지를 받을 수 있으며, 여기서 grok-imagine이 제품 작업에서 단일 프레임 애니메이터와 차별화됩니다. 장면으로 사용할 라이프스타일 이미지를 주고 추가로 깨끗한 제품 이미지를 정체성 보험으로 주면, 모델이 둘을 조화시킵니다. 장면은 첫 번째 이미지에서, 제품의 정확한 트림, 스트랩, 지퍼는 두 번째 이미지에서 고정됩니다:

The same burnt-orange weekender bag rests on a weathered wooden bench in a
sunlit loft; a gentle push-in as dust motes drift through warm window light,
soft shadows slide slowly across the bench, the bag and its dark leather trim
stay exactly consistent with the reference images, calm lifestyle-catalog mood.

실제 출력 — grok-imagine/image-to-video, 6초 @ 720p, 9:16, 두 장의 참조 이미지(벤치 라이프스타일 이미지 + 흰색 배경 제품 이미지). 첫 생성, 편집 없음.

프롬프트의 "참조 이미지와 일치" 문구에 주목하세요. 여러 참조 이미지를 사용할 때 이를 명시적으로 말하면 모델이 추가 이미지를 혼합할 두 번째 장면이 아니라 정체성 제약으로 취급하도록 돕습니다. 이것이 브랜드 계정의 일일 게시 패턴입니다. 각 SKU당 제품 이미지를 하나 촬영(또는 생성)한 다음, 애니메이션화하려는 모든 라이프스타일 영상에서 이를 일관성 앵커로 재사용합니다.

길이와 초안 티어 경제성

길이는 6~30초이며, 해상도가 예산 레버입니다. 480p는 초당 가격이 720p의 약 절반입니다. 피드가 어차피 공격적으로 압축되므로 합리적인 파이프라인은 480p로 초안을 만들고, 승자를 720p로 재제작하는 것입니다. 더 긴 길이는 모델이 천천히 전개할 공간을 줍니다. 아래는 차 통 정지 이미지에 연속적인 분위기 운동을 적용한 12초 480p 초안 티어 영상입니다:

Moody slow dolly-in on the matte-black tea tin standing on slate, steam curls
up lazily behind it, a soft beam of morning light sweeps across the embossed
label, tiny tea leaves tumble gently onto the slate in the final seconds, dark
premium atmosphere, label text unchanged and legible.

실제 출력 — grok-imagine/image-to-video, 12초 @ 480p, 단일 참조 이미지. 첫 생성, 편집 없음(정사각형 소스 정지 이미지와 일치하게 정사각형으로 전달). 비용: $0.137.

480p 렌더링 비용은 $0.0114/초입니다. 12초 영상 전체가 13.7센트밖에 들지 않았습니다. 각 제품에 대해 세 가지 프롬프트 변형을 시도하고 실제로 게시하는 하나에만 720p 요금을 지불할 만큼 저렴합니다. 프롬프트의 "레이블 텍스트 불변 및 읽기 가능" 문구에 주목하세요. 패키지 텍스트는 이미지-투-비디오에서 가장 먼저 뭉개지는 것이며, 이를 언급하는 것이 가장 저렴한 보호 조치입니다.

카탈로그 배치 처리

위의 모든 것은 작업이 비동기이므로 선형적으로 확장됩니다. 먼저 전체 배치를 제출한 다음 폴링합니다. 제품 목록을 위한 최소 배치 러너:

products = [
    {"sku": "weekender-orange", "refs": ["https://cdn.example.com/weekender.jpg"],
     "prompt": "Slow cinematic orbit around the bag, studio light on the brass zippers, background clean, product unchanged."},
    {"sku": "tea-tin-black", "refs": ["https://cdn.example.com/tea-tin.jpg"],
     "prompt": "Moody slow dolly-in, steam drifting, light sweeping the embossed label, label text unchanged."},
    # ... 카탈로그의 나머지
]

jobs = []
for p in products:
    tid = submit({
        "prompt": p["prompt"],
        "image_urls": p["refs"],
        "duration": 6,
        "resolution": "480p",     # 초안 티어
        "aspect_ratio": "9:16",
    })
    jobs.append((p["sku"], tid))

for sku, tid in jobs:
    task = wait(tid)
    url = task["output"][0]["url"]
    subprocess.run(["curl", "-s", "-o", f"{sku}.mp4", url], timeout=180)
    print(f"{sku}: done")

이 파이프라인을 실행할 때의 실용적인 배치 요점:

• 먼저 제출, 나중에 폴링. 각 렌더링은 몇 분이 걸리며 서버에서 병렬로 실행됩니다. "제출-대기-제출"을 직렬화하면 이 병렬성을 낭비합니다.
• 콘텐츠 유형당 하나의 평평한 프롬프트 템플릿 유지(제품 이미지에는 궤도, 라이프스타일 이미지에는 푸시인), 제품 명사만 삽입. 전체 피드의 일관성이 각 영상의 기발함보다 더 중요합니다.
• 예산 확인: 50개 SKU 카탈로그를 6초/480p로 초안하면 50 × $0.068 ≈ $3.42. 최고의 10개를 720p로 승격하면 10 × $0.128 ≈ $1.28 추가. 한 달치 일일 제품 영상이 스튜디오 촬영 한 시간보다 저렴합니다.

숏폼 게시 노트

• 세로형에는 세로형 참조 이미지가 필요합니다. 위에서 언급했듯이 참조 이미지의 종횡비가 종종 aspect_ratio를 덮어씁니다. 영상이 피드에 게시된다면 제출 전에 정지 이미지를 9:16으로 자르세요. 완성된 정사각형 렌더링을 세로형으로 자르면 대부분의 픽셀을 잃습니다.
• 첫 1초가 훅입니다 — 운동이 즉시 시작되는 프롬프트("카메라 궤도", "푸시인")가 느린 페이드인보다 완주율에서 우수합니다.
• 영상에는 모델이 생성한 분위기 오디오 트랙이 포함됩니다. 우리가 생성한 모든 출력에는 AAC 스트림이 있습니다. 일부 영상은 미묘한 스튜디오 분위기이고, 일부는 거의 무음입니다. 이를 제어할 입력 필드가 없으므로 게시할 때 완성된 사운드트랙으로 취급하지 말고 자체 음악이나 보이스오버로 교체할 계획을 세우세요.
• 루프 친화성: 궤도와 빛 스윕은 공개로 끝나는 영상보다 훨씬 잘 루프됩니다. 자동 루프 피드(Shorts, Reels)의 경우 위의 궤도 패턴이 매끄럽게 재생됩니다.

자주 묻는 질문

렌더링에 얼마나 걸리나요? 이 글의 6초 영상은 각각 몇 분씩 렌더링되었고, 12초 영상은 조금 더 걸렸습니다. 대화형 호출이 아니라 비동기 큐로 취급하세요. 배치로 제출하고 폴링하세요.

생성된 이미지를 참조 이미지로 사용할 수 있나요? 네. 참조 URL은 공개적으로 가져올 수 있기만 하면 됩니다. 이 글의 세 소스 정지 이미지는 그 자체로 API 생성 제품 이미지(seedream-5.0-lite 실행에서 나온)로, 우리 소재 라이브러리에서 가져온 것입니다. 완전히 합성된 정지 이미지-투-비디오 파이프라인입니다.

1080p 또는 30초 초과는요? 이 엔드포인트는 720p와 30초로 제한됩니다. 숏폼 피드에는 이것이 최적 구간입니다. 더 높은 해상도가 필요하면 후처리에서 업스케일하거나 모델 카탈로그에서 현재 옵션을 확인하세요.

grok-imagine-1.5/image-to-video와 어떻게 다른가요? 1.5 프리뷰 엔드포인트는 범위를 운동 품질과 맞바꿉니다. 1~15초 길이, 운동 업그레이드, 초당 가격 동일. 이 1.0 엔드포인트는 6~30초를 제공합니다. 1.5의 기본 사항은 다른 상세 글에서 다뤘습니다.

텍스트-투-비디오 버전이 있나요? 네 — grok-imagine/text-to-video, 동일한 작업 인터페이스, 프롬프트 입력만 있습니다. 브랜드/제품 일관성이 중요할 때는 이미지-투-비디오가 올바른 선택이고, 처음부터 소재를 생성해야 할 때는 텍스트-투-비디오를 사용하세요.

---

제품 정지 이미지와 API 키가 있다면, 첫 피드 영상까지는 POST /v1/tasks 한 번만 남았습니다. 대시보드에서 키를 받고, grok-imagine/image-to-video 모델 페이지에서 시작하여 위의 궤도 프롬프트로 제품 이미지 하나를 애니메이션화하세요. 초안당 13센트라면 이 모델을 배우는 가장 빠른 방법은 실행하는 것입니다.