Grok Imagine API로 텍스트-투-비디오 사용하는 방법: curl, Python 및 실행 가능한 요청

Grok Imagine은 xAI의 비디오 생성 모델이며, HiAPI는 다른 모든 생성 모델과 동일한 통합 비동기 엔드포인트인 POST /v1/tasks를 통해 텍스트-투-비디오 변형을 제공합니다. 프롬프트(선택적으로 duration, mode, aspect_ratio, resolution 포함)를 보내면 즉시 taskId를 받고, 작업이 완료되면 .mp4 URL을 얻습니다.

이 가이드는 실행 가능한 요청으로 가는 최단 경로입니다: 정확한 입력 스키마(라이브 API로 검증됨, 필드명을 잘못 추측했을 때 발생하는 400 오류 포함), 복사-붙여넣기 가능한 curl 흐름, 폴링이 포함된 작은 Python 클라이언트, 그리고 프로덕션에서 사용할 콜백 패턴입니다.

무엇을 만들며 무엇이 필요한가

목표: grok-imagine/text-to-video를 통해 순수 HTTP만으로 텍스트 프롬프트를 6–30초 비디오 클립으로 변환합니다.

필요한 것은 단 하나: HiAPI API 키. HiAPI 대시보드에서 생성하세요 — 단일 키가 모든 모델에서 작동하므로 이미 HiAPI에서 이미지 모델을 호출했다면 동일한 키가 여기서도 작동합니다. 요청은 표준 bearer 헤더로 인증됩니다:

Authorization: Bearer sk-<your-key>

입력 스키마 (코드를 작성하기 전에)

작업 API는 모델별로 input을 엄격하게 검증합니다 — 알 수 없는 필드는 조용히 무시되지 않고 400으로 거부됩니다. 다음은 grok-imagine/text-to-video의 전체 스키마입니다:

필드	유형	필수	값	기본값
prompt	string	예	최대 5000자, 영어가 가장 잘 작동	—
duration	integer	아니오	6–30 (초)	6
mode	enum	아니오	fun, normal	normal
aspect_ratio	enum	아니오	2:3, 3:2, 1:1, 16:9, 9:16	2:3
resolution	enum	아니오	480p, 720p	480p

사전에 알아두어야 할 세 가지:

• mode는 '모션 모드' 스위치입니다. normal은 균형 잡혀 있고 fun은 더 창의적이고 과장된 모션을 생성합니다. 다른 곳에서 Grok Imagine의 모드가 다른 이름으로 설명된 것을 보았다면, API 매개변수는 mode입니다 — motion_mode 같은 것을 보내면 400 additional properties 'motion_mode' not allowed가 반환됩니다.
• duration은 비용에 선형적으로 영향을 미칩니다. Grok Imagine은 출력 초 단위로 과금하므로 30초 클립은 6초 클립 비용의 5배입니다. 현재 초당 요금은 HiAPI 가격 페이지를 참조하세요.
• 기본 종횡비는 2:3 (세로)입니다. 가로 화면을 원한다면 명시적으로 16:9를 전달하세요 — 이 점은 기본이 가로인 모델에서 마이그레이션한 사용자를 놀라게 합니다.

범위를 벗어난 값은 설명 메시지와 함께 빠르게 실패합니다. 예를 들어 duration: 31은 다음을 반환합니다:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: duration: maximum: got 31, want 30"}

최소 실행 예제: curl

두 번의 호출: 작업 생성 후 폴링.

1. 작업 생성:

export HIAPI_API_KEY="sk-..."

curl -sS -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-video",
    "input": {
      "prompt": "A red fox trotting through fresh snow at dawn, low golden light, cinematic tracking shot",
      "duration": 6,
      "mode": "normal",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

모델 id는 순수 문자열 grok-imagine/text-to-video입니다 — 공급자 접두사도, 버전 접미사도 없습니다.

2. 종료 상태까지 폴링:

TASK_ID="tk-hiapi-..."

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "grok-imagine/text-to-video",
#     "output": [
#       {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1783300000}
#     ],
#     ...
#   }
# }

.mp4 URL은 임시입니다 — expireAt은 약 1주일 후의 Unix 타임스탬프입니다. 작업 성공 후 즉시 바이트를 다운로드하고 직접 영구 저장하세요. 사용자에게 노출되는 어떤 곳에서도 temp.hiapi.ai URL을 핫링크하지 마세요. (만료된 출력 링크를 겪었다면 그 이유가 여기 있습니다 — hiapi 출력 URL 만료: 만료 전에 다운로드하세요 참조.)

Python: 작은 폴링 클라이언트

동일한 흐름의 재사용 스크립트 — 생성, 데드라인 폴링, 다운로드:

# pip install requests
import os
import time

import requests

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


def create_task(prompt: str, duration: int = 6, mode: str = "normal",
                aspect_ratio: str = "16:9", resolution: str = "720p") -> str:
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "grok-imagine/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # 6-30, billed per second
            "mode": mode,                  # "normal" | "fun"
            "aspect_ratio": aspect_ratio,  # "2:3" | "3:2" | "1:1" | "16:9" | "9:16"
            "resolution": resolution,      # "480p" | "720p"
        },
    }, timeout=60)
    data = resp.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 = 900, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task(
        "A red fox trotting through fresh snow at dawn, low golden light, "
        "cinematic tracking shot",
        duration=6,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    video = requests.get(url, timeout=120).content   # expires — persist now
    with open("fox.mp4", "wb") as f:
        f.write(video)
    print(f"saved fox.mp4 ({len(video)} bytes)")

6초 클립은 일반적으로 위의 15분 데드라인보다 훨씬 빨리 완료됩니다. 더 긴 duration은 비례적으로 더 오래 걸리므로 30초 작업에는 이 느슨한 타임아웃을 유지하세요.

프로덕션 고려 사항

폴링 대신 콜백 사용. 스크립트를 넘어서는 모든 경우에는 생성 시 최상위 callback 객체를 전달하세요. HiAPI가 종료 상태의 작업 상태를 엔드포인트로 POST합니다 — 폴링 루프를 감시할 필요가 없습니다:

{
  "model": "grok-imagine/text-to-video",
  "input": {"prompt": "...", "duration": 12},
  "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"}
}

when은 "final"만 허용합니다(작업이 success 또는 fail에 도달하면 한 번 POST를 받으며, 증분 진행 상황은 받지 않습니다). 경험칙: 폴링은 CLI, 배치 작업 및 모든 단명 컨텍스트에 적합하고, 콜백은 웹 백엔드에 적합합니다. 그렇지 않으면 워커 용량이 수 분간의 렌더링에 묶이게 됩니다. 콜백 엔드포인트가 아무것도 받지 못하는 것 같다면 hiapi 작업 콜백이 발생하지 않는 이유를 확인하세요.

멱등성. 작업 생성은 멱등이 아닙니다 — 타임아웃된 생성 요청을 재시도하면 두 개의 과금 작업이 발생할 수 있습니다. taskId를 받는 즉시 기록하고, 모호한 실패(생성 시 네트워크 타임아웃)가 발생하면 재제출 전에 작업 기록을 확인하세요. duration이 초 단위로 과금되므로 중복된 30초 작업은 비용이 큰 중복입니다.

오류 처리. 실제로 보게 될 두 가지 오류 유형:

• 스키마 400 오류 (error_code: "INVALID_REQUEST") — 잘못된 필드 이름, 범위를 벗어난 duration, 잘못된 enum 값. 이들은 결정적입니다. 요청을 수정하고 재시도하지 마세요.
• 인증 실패 — 잘못된 키 또는 이 모델에 접근할 수 없는 키는 401을 반환하며 "code": "permission_denied"와 메시지 "This API key cannot use the selected model."가 포함됩니다. 대시보드에서 키를 확인하고 해당 모델이 활성화되어 있는지 확인하세요.
• 작업 수준 실패 — 생성은 성공했지만 이후 작업이 status: "fail"로 종료되고 error 객체(콘텐츠 정책, 업스트림 용량)가 포함됩니다. 이들은 백오프 방식으로 한 번 재시도할 가치가 있습니다. 작업이 handling에 멈춘 것 같다면 멈추거나 타임아웃된 /v1/tasks 작업 진단을 참조하세요.

다음 단계

• Grok Imagine 텍스트-투-비디오 모델 페이지 — 플레이그라운드 및 현재 가격
• 모델 입력 참조 — 이 모델의 정식 스키마
• 작업 생성 및 작업 세부정보 가져오기 — 전체 비동기 API 봉투
• 빠른 시작 — 첫 HiAPI 호출을 엔드투엔드로 완료하고, 인증에서 키 처리 방법을 확인하세요

자주 묻는 질문

Grok Imagine API란 무엇이며 어떻게 접근하나요? Grok Imagine은 xAI의 비디오 생성 모델입니다. HiAPI를 통해 단일 HiAPI 키로 통합 POST /v1/tasks 엔드포인트에서 grok-imagine/text-to-video로 호출합니다 — 별도의 xAI 계정이나 SDK가 필요 없습니다.

Grok Imagine 비디오는 얼마나 길 수 있나요? duration은 6~30초의 정수를 허용합니다(기본값 6). 해당 범위를 벗어난 값은 생성 시 400으로 거부되며, 과금은 출력 초 단위로 계산됩니다.

fun과 normal 모드의 차이는 무엇인가요? normal(기본값)은 균형 잡히고 사실적인 모션을 제공하고, fun은 더 창의적이고 과장된 쪽입니다. 이는 API가 노출하는 유일한 모션 스타일 스위치입니다 — 계정별이 아니라 요청별로 선택합니다.

grok-imagine/text-to-video는 1080p를 지원하나요? 현재 지원하지 않습니다 — resolution은 480p(기본값) 또는 720p를 허용합니다. 더 높은 출력 해상도가 필요하면 다운스트림에서 업스케일하거나 모델 페이지에서 다른 비디오 모델을 비교하세요.

Grok Imagine으로 기존 이미지를 애니메이션화할 수 있나요? 이 모델로는 안 됩니다 — 텍스트만 지원합니다. 동일한 작업 엔드포인트에 이미지 입력을 받는 별도의 grok-imagine/image-to-video 모델이 있으며, 비동기 라이프사이클(생성 → 폴링/콜백 → 다운로드)은 완전히 동일합니다.

Grok Imagine API에 무료 티어가 있나요? 생성은 비디오 초 단위로 HiAPI 잔액에서 과금됩니다 — 키 없이 무료로 사용할 수 있는 엔드포인트는 없습니다. 현재 요금은 가격 페이지를 참조하세요. 이 분야에서 '무료'가 현실적으로 어떤 모습인지는 무료 텍스트-투-비디오 API 비교에서 다양한 옵션을 다룹니다.