HiAPI
Ko
블로그

튜토리얼

hiapi API로 grok-imagine-1.5/image-to-video 사용하는 방법: curl, Python, 그리고 바로 실행 가능한 요청

Jul 7, 2026
hiapi API로 grok-imagine-1.5/image-to-video 사용하는 방법: curl, Python, 그리고 바로 실행 가능한 요청

간단 요약

  • 무엇인가: hiapi의 통합 태스크 API를 통해 grok-imagine-1.5/image-to-video로 정적 이미지를 짧은 영상으로 애니메이션화하는 방법을 다루는 복사 가능한 가이드입니다.
  • 흐름: POST /v1/tasks로 태스크를 생성하고, GET /v1/tasks/<taskId>를 폴링하거나(또는 콜백 등록) 만료 전에 data.output[0].url에서 MP4를 다운로드합니다.
  • 입력 스키마(실제 API로 검증됨): image_urls 항목 하나만 허용하며, 선택적 prompt, duration은 1–15초, resolution은 480p/720p, aspect_ratio는 auto, 1:1, 16:9, 9:16, 3:2, 2:3 중 하나입니다. 다른 필드는 허용되지 않습니다.

무엇을 만들고 무엇을 준비할까요

목표: 소스 이미지와 움직임 프롬프트를 보내 Grok Imagine 1.5가 생성한 짧은 MP4 영상 클립을 받는 것입니다.

사전 조건:

  • hiapi API 키 — 대시보드에서 생성합니다. 키는 sk-... 형태이며 Authorization: Bearer 요청 헤더에 넣습니다.
  • 공개 접근 가능한 소스 이미지 URL(JPEG/PNG). API가 서버 측에서 이미지를 가져오므로 localhost 링크나 인증이 필요한 파일은 사용할 수 없습니다.
  • 아무 HTTP 클라이언트. 아래 예시는 curl과 Python의 requests를 사용합니다.

모델 id는 접미사가 없는 순수 문자열 grok-imagine-1.5/image-to-video입니다.

최소 실행 예시: curl

태스크 생성:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-1.5/image-to-video",
    "input": {
      "image_urls": ["https://example.com/product-shot.jpg"],
      "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

제출에 성공하면 200과 taskId가 반환됩니다:

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5", "status": "queued" },
  "message": "success"
}

태스크가 종료 상태에 도달할 때까지 폴링합니다(status는 queued → handling → success 또는 fail 순으로 진행):

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5" \
  -H "Authorization: Bearer sk-YOUR_KEY"

완료된 태스크(실제 응답, 잘림):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5",
    "model": "grok-imagine-1.5/image-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "video",
        "url": "https://temp.hiapi.ai/.../01KWVVSTX0TJ32AD45F6ZQ08W5-0.mp4",
        "expireAt": 1783951451
      }
    ]
  },
  "message": "success"
}

⚠️ storage: "temp"와 expireAt은 다운로드 URL이 임시임을 의미합니다. 태스크가 성공하면 즉시 MP4를 다운로드해 자체 인프라에 저장하세요 — 핫링크하지 마세요.

최소 실행 예시: Python

전체 스크립트 — 생성, 폴링, 다운로드:

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json={
    "model": "grok-imagine-1.5/image-to-video",
    "input": {
        "image_urls": ["https://example.com/product-shot.jpg"],
        "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
        "duration": 6,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll for the result (image-to-video usually lands well within a few minutes)
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS).json()["data"]
    status = task["status"]
    if status == "success":
        break
    if status == "fail":
        raise RuntimeError(f"generation failed: {task.get('error')}")
    time.sleep(5)
else:
    raise TimeoutError(f"task {task_id} still not finished after 10 min")

# 3. Download immediately — the output URL expires
video_url = task["output"][0]["url"]
mp4 = requests.get(video_url, timeout=120)
mp4.raise_for_status()
with open("clip.mp4", "wb") as f:
    f.write(mp4.content)
print("saved clip.mp4,", len(mp4.content), "bytes")

입력 레퍼런스(스키마가 실제로 허용하는 것)

이 제약은 추측이 아니라 실제 검증기에서 가져온 것입니다 — 다른 내용을 보내면 정확한 메시지와 함께 400 INVALID_REQUEST가 반환됩니다:

필드 타입 규칙
image_urls 문자열 배열 필수, 정확히 1개 URL(maxItems: 1)
prompt 문자열 선택 — 움직임, 카메라 무브, 분위기 설명
duration 정수 1–15초
resolution 문자열 480p 또는 720p
aspect_ratio 문자열 auto, 1:1, 16:9, 9:16, 3:2, 2:3

설명:

  • 이 모델에는 seed, negative_prompt, fps, motion_strength, camera_fixed 필드가 없습니다. 스키마가 알 수 없는 속성을 거부하므로(additional properties ... not allowed), 움직임과 카메라 동작은 전적으로 prompt로 제어하세요.
  • 태스크당 참조 이미지는 하나만 가능합니다. 두 개를 보내면 image_urls: maxItems: got 2, want 1이 반환됩니다.
  • aspect_ratio: "auto"는 소스 이미지 자체의 비율을 따릅니다 — 보통 제품 사진이 원하는 효과입니다.
  • 이전 grok-imagine/image-to-video는 클립당 최대 30초를 허용하지만, 1.5는 최대 15초입니다. 초당 가격은 동일합니다: 480p는 $0.015, 720p는 $0.0282.

프로덕션 환경 유의사항

폴링 대신 콜백 사용. 스크립트 외의 모든 상황에서는 태스크 생성 시 웹훅을 등록하고 폴링 루프를 생략하세요:

{
  "model": "grok-imagine-1.5/image-to-video",
  "input": { "image_urls": ["https://example.com/shot.jpg"], "duration": 6 },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

callback.url은 공개 http(s) 엔드포인트여야 하며 when은 "final"만 지원합니다 — 태스크가 success 또는 fail에 도달하면 POST를 한 번 받습니다. 폴링은 CLI와 배치 작업에 적합하고, 대량의 클립을 생성하면서 폴링 서비스 무리를 배포하고 싶지 않을 때는 콜백이 더 낫습니다. 웹훅 유실로 태스크가 방치되지 않도록 폴백 폴링(예: 몇 분마다 콜백을 받지 못한 태스크 확인)을 남겨두세요.

멱등성. 태스크 생성은 서버 측에서 중복 제거되지 않으므로 네트워크 타임아웃 후 단순 재시도하면 중복 제출과 중복 청구가 발생할 수 있습니다. 생성 호출이 반환되면 즉시 taskId를 영구 저장하고, 재시도 시 자체 저장소를 먼저 확인하세요. 제출과 저장 사이에 크래시가 발생하면 최근 태스크를 조회(GET /v1/tasks)해 재제출 전에 모델 + 생성 시각으로 매칭하세요.

오류 처리. 실제로 마주칠 실패 모드:

  • 401과 {"error": {"code": "permission_denied", "type": "hiapi_error", ...}} — 키가 잘못되었거나 키에 해당 모델 접근 권한이 없습니다. 응답에 지원용 request_id가 포함됩니다.
  • 400과 error_code: "INVALID_REQUEST" — 스키마 위반이며 message가 구체적인 필드와 규칙을 알려줍니다(예: duration: maximum: got 99, want 15). 요청 본문을 수정하세요, 맹목적으로 재시도하지 마세요.
  • 402 잔액 부족 — 비디오 모델은 제출 시 할당량을 사전 검사합니다. 충전 후 다시 제출하세요.
  • 태스크 자체가 status: "fail" — 생성 측 실패; data.error를 확인하고 백오프로 재시도하세요. 소스 이미지에 접근할 수 없는 것이 흔한 원인입니다.

출력 즉시 저장. 반복할 가치가 있습니다: output[0].url은 expireAt 타임스탬프가 있는 임시 저장소에 있습니다. success를 본 즉시 MP4를 자체 스토리지 버킷으로 스트리밍하세요. 파이프라인이 성공 후 다운로드 전에 크래시하면 id로 태스크를 다시 조회하세요 — URL은 expireAt까지 유효하며 영구적이지 않습니다.

관련 읽기

자주 묻는 질문

grok-imagine-1.5 영상은 얼마나 길 수 있나요? 1~15초이며 정수 duration 필드로 설정합니다. 더 길게 요청하면 400(duration: maximum: got X, want 15)이 반환됩니다. 최대 30초가 필요하면 이전 grok-imagine/image-to-video를 사용하세요.

어떤 해상도와 화면 비율을 지원하나요? resolution은 480p 또는 720p; aspect_ratio는 auto, 1:1, 16:9, 9:16, 3:2, 2:3입니다. 720p의 9:16은 Shorts/Reels 스타일 세로 클립에 가장 선호되는 조합입니다.

참조 이미지를 여러 장 전달할 수 있나요? 아니요 — 이 모델의 image_urls는 정확히 URL 하나만 받습니다. 다중 참조 워크플로에서는 태스크를 연결하거나 참조 이미지를 먼저 단일 입력 이미지로 합성하세요.

seed나 네거티브 프롬프트가 있나요? 없습니다. 입력 스키마가 seed, negative_prompt, fps 및 유사 필드를 즉시 거부합니다. 움직임 스타일, 카메라 무브, 분위기는 모두 prompt 문자열로 제어합니다.

비용은 얼마인가요? 생성된 영상의 초 단위로 청구됩니다: 480p는 초당 $0.015, 720p는 초당 $0.0282. 6초 클립은 480p에서 $0.09, 720p에서 $0.1692입니다. duration을 전달하지 않으면 기본 8초입니다. 더 많은 예시는 Grok Imagine 1.5 가격 세부 정보를 참고하세요.

왜 요청이 401 permission_denied를 반환하나요? API 키가 잘못되었거나 폐기되었거나, 해당 모델 접근 권한이 없기 때문입니다. 대시보드에서 키를 확인하고 Authorization: Bearer sk-...를 보내고 있는지 확실히 하세요 — Bearer 접두사가 빠지면 동일한 오류가 발생합니다.

폴링 없이 영상이 준비된 것을 어떻게 알 수 있나요? 태스크 생성 시 "callback": {"url": "https://your-endpoint", "when": "final"}를 붙이세요. 태스크가 종료 상태에 도달하면 hiapi가 엔드포인트로 POST를 보냅니다. 폴백으로 GET /v1/tasks/<taskId>를 폴링하세요.

왜 제 영상 URL이 며칠 후 작동을 멈추나요? 출력은 임시 저장소에 있으며 각 출력 항목에 expireAt 타임스탬프가 있습니다. success 후 즉시 파일을 다운로드하고 자체 스토리지에서 제공하세요.

태그grok비디오 생성이미지-투-비디오튜토리얼API

관련 글

모든 아티클 보기 →

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기