튜토리얼

grok-imagine-1.5-lite 텍스트-투-비디오 API 사용 방법(curl + Python)

Oct 21, 2026

한 문장으로 소리가 포함된 짧은 영상을 생성하고 싶다면, grok-imagine-1.5-lite/text-to-video는 hiapi에서 1080P까지 지원하는 가장 저렴한 선택입니다. 이 모델은 프롬프트 하나를 받아 1–15초 길이의 오디오가 이미 믹스된 MP4를 반환하며, 플랫폼의 다른 모든 모델과 동일한 통합 작업 API 위에서 동작합니다. 이 페이지에서는 바로 붙여넣어 실행할 수 있는 요청, 정확한 스키마(실시간 엔드포인트로 검증한 것이며 명세서에서 복사한 것이 아님), 실제 응답의 모습, 그리고 제가 테스트하면서 마주친 함정들을 제공합니다.

아래 내용은 모두 2026-10-21에 실시간 API와 대조하여 검증했습니다. 가격은 제가 실측한 값이며, 가격이 변경되면 가격 페이지를 기준으로 합니다.

1. 무엇을 만들고 무엇을 준비해야 하는가

목표: 텍스트 프롬프트 하나를 보내고 다운로드 가능한 오디오 포함 MP4 클립을 받는 것.

필요한 것은 단 하나, hiapi API 키입니다. 콘솔에서 생성하여 서버 측에 보관하세요. sk-... 형태이며 Authorization: Bearer 요청 헤더에 넣습니다. 키 없이 호출할 수 있는 경로는 없으며, 아래의 모든 요청은 인증을 거쳐야 합니다.

이 모델은 비동기입니다. POST 응답에서 영상을 바로 받을 수 없습니다. 먼저 작업을 생성하여 taskId를 받은 다음, 작업이 완료되어 출력 URL이 나올 때까지 폴링(또는 콜백 사용)합니다.

2. 최소 실행 예제

두 단계: 작업 생성, 그다음 결과 폴링.

작업 생성(curl)

curl -s -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-lite/text-to-video",
    "input": {
      "prompt": "새벽녘, 붉은 여우 한 마리가 새로 내린 눈을 밟아 지나가고, 내쉬는 숨결이 하얀 김으로 피어오른다. 부드러운 아침 햇살, 잔잔한 주변 바람 소리. 영화적, 자연스러운 색감. 텍스트 없음.",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

구조에 주목하세요. model은 최상위에 있고, 나머지 모든 내용은 input 아래에 중첩됩니다. 필드를 평면적으로 보내면(input 래핑 없이) API가 invalid input: must be a JSON object로 요청 본문 전체를 거부합니다. 이것이 가장 흔한 오류입니다.

생성에 성공하면 즉시 작업 id가 반환됩니다.

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

결과 폴링(Python)

import time, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEAD = {"Authorization": "Bearer sk-YOUR_KEY", "Content-Type": "application/json"}

def generate(prompt, duration=5, resolution="720p", aspect_ratio="16:9"):
    r = requests.post(BASE, headers=HEAD, json={
        "model": "grok-imagine-1.5-lite/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # integer, 1–15
            "resolution": resolution,      # "480p" | "720p" | "1080p"
            "aspect_ratio": aspect_ratio,  # see schema below
        },
    })
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    # Poll the SAVED task_id. A single transient network error is not a failure —
    # keep polling the same id rather than re-creating (re-creating bills again).
    deadline = time.time() + 300
    while time.time() < deadline:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEAD, timeout=30).json()
        except requests.RequestException:
            time.sleep(5); continue
        task = d.get("data") or {}
        status = task.get("status")
        if status == "success":
            return task["output"][0]["url"]
        if status == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

print(generate("새벽녘, 붉은 여우 한 마리가 새로 내린 눈을 밟아 지나가고, 잔잔한 주변 바람 소리. 영화적."))

스키마(실시간 검증)

필드는 input 안에 넣습니다. 이 스키마는 폐쇄형입니다. 인식하지 못하는 key가 있으면 400을 반환하므로 seed, negative_prompt, motion_mode는 보내지 마세요(여기에는 존재하지 않으며, 모든 카메라 및 운동 방향은 프롬프트 문구로 표현합니다).

필드	유형	필수 여부	허용 값
`prompt`	string	예	자유 텍스트
`duration`	integer	예	1–15(정수 초, `5.5`는 거부됨)
`resolution`	string	—	`480p`, `720p`, `1080p`
`aspect_ratio`	string	—	`16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16`

이 모델에는 auto 가로세로 비율이 없습니다(같은 세대의 이미지-투-비디오 모델에는 있지만, 이 텍스트-투-비디오 엔드포인트에는 없습니다). 비율을 명시적으로 지정하지 않으면 모델 기본 비율이 적용됩니다.

다음은 완료된 작업의 실제 응답입니다.

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

다음은 이 모델이 생성한 클립입니다(hiapi가 grok-imagine-1.5-lite/text-to-video용으로 제공하는 참고 출력이며, 문서 예제 프롬프트 "일출 무렵, 유리 열기구가 계단식 논 위를 떠다닌다"로 생성):

3. 운영 환경에 적용하기

폴링 대신 콜백을 사용하세요. 폴링은 스크립트에는 괜찮지만, 서버에서는 callback을 추가하여 요청을 계속 열어둘 필요가 없게 하세요. 작업이 종료 상태에 도달하면 플랫폼이 작업 상세 정보를 귀하의 URL로 POST합니다.

{
  "model": "grok-imagine-1.5-lite/text-to-video",
  "input": { "prompt": "...", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your.app/hooks/hiapi", "when": "final" }
}

이 작업 유형에서 when은 "final"만 허용합니다. 핸들러에서는 taskId로 중복 제거하세요. 콜백이 재시도될 수 있으므로 핸들러를 멱등하게 취급해야 합니다.

출력 URL은 만료됩니다. storage: "temp"와 expireAt unix 타임스탬프에 주목하세요. 임시 출력은 temp.hiapi.ai에 약 7일간 보관된 후 404를 반환합니다. 핫링크를 저장하지 마세요. 작업이 성공하는 즉시 바이트를 다운로드하거나, 스토리지 전송 엔드포인트를 호출하여 TTL 만료 전에 결과물을 영구 스토리지로 옮기세요.

비용은 출력 초 단위로 계산됩니다. 과금은 duration과 요청한 해상도에 의해서만 결정됩니다. 테스트 기준: 480P $0.029/s, 720P $0.043/s, 1080P $0.20/s. 따라서 5초 720P 클립은 약 $0.215, 5초 1080P 클립은 약 $1.00, 1초 480P 클립은 약 $0.029입니다. 1080P 요금은 720P의 약 5배이므로, 정말로 해당 해상도가 필요할 때만 사용하세요. 최신 수치는 가격 페이지를 참고하세요.

오류 처리. 거부된 요청은 HTTP 400으로 반환되며, 로깅하고 그에 따라 처리할 수 있는 정확한 메시지를 포함합니다. 검증은 작업 생성 이전에 이루어지므로 여기서의 400은 비용이 발생하지 않습니다. 제가 실제로 트리거한 실제 응답입니다.

invalid input: duration: maximum: got 999, want 15
invalid input: duration: minimum: got 0, want 1
invalid input: duration: got number, want integer
invalid input: resolution: value must be one of '480p', '720p', '1080p'
invalid input: aspect_ratio: value must be one of '16:9', '4:3', '3:2', '1:1', '2:3', '3:4', '9:16'
invalid input: prompt: missing required field "prompt"
invalid input: <root>: additional properties 'bogus_field' not allowed

작업이 수락된 후 실패하면 HTTP 오류가 아니라 data.status: "fail"과 상세 엔드포인트에 첨부된 data.error 객체로 나타납니다. 따라서 status를 확인하고 폴링의 HTTP 상태 코드에 의존하지 마세요.

4. 제가 실제로 관찰한 것

엔드투엔드 흐름을 확인하기 위해 실제로 한 번 생성했습니다(스키마만이 아님): duration: 1, resolution: "480p", aspect_ratio: "16:9".

실제로 동작하며 과금됩니다 — POST가 taskId를 반환했고, 작업은 실제 출력 URL을 가지고 완료되었습니다. 서버에서 1초 클립을 렌더링하는 데 실제로 약 51초가 걸렸습니다. 아주 작은 클립도 즉시 생성되지 않으므로 폴링 마감 시간을 넉넉히 잡으세요(저는 300초로 설정).
작업은 중간 상태를 거칩니다. status 필드는 handling → archiving → success 순으로 진행됩니다. success와 fail만 종료 상태이므로 archiving을 완료로 착각하지 마세요.
480P는 16:9에서 848×480 H.264로 렌더링됩니다. 다운로드한 파일에 ffprobe를 실행하면 H.264 비디오 스트림(848×480)과 내장된 MJPEG 썸네일 스트림이 나옵니다. 이 495 KB 파일은 유효한 MP4입니다.
오디오는 항상 내장됩니다. 제 프롬프트가 "잔잔한 주변 바람 소리"만 언급했음에도 출력에는 AAC 오디오 트랙이 포함되어 있었습니다. 모델이 어울리는 오디오를 합성하여 같은 MP4에 믹스합니다. 별도의 오디오 URL도, 이를 비활성화하는 스위치도 없습니다. 무음 클립이 필요하면 직접 오디오 트랙을 제거하세요(ffmpeg -an).

범위 참고: 저는 API 계약, 위의 세 가지 오류 유형, 그리고 한 번의 480P 렌더링을 검증했습니다. 720P/1080P 출력 품질이나 긴(15초) 길이에 대해서는 벤치마크하지 않았으므로 이에 대한 품질 단정은 하지 않습니다. 스키마가 이를 허용하고 초 단위로 과금된다는 점만 말씀드립니다.

5. Lite와 표준 Grok Imagine 비디오 API 비교

구축 전에 올바른 엔드포인트를 선택하세요.

grok-imagine-1.5-lite/text-to-video(이 페이지): 480P/720P/1080P, 1–15초(따라서 1초 또는 2초 클립 생성 가능), 가격 $0.029–$0.20/s. hiapi가 호스팅하는 유일한 1.5세대 텍스트-투-비디오 엔드포인트이며, 1080P에 도달할 수 있는 유일한 Grok t2v 등급입니다.
grok-imagine/text-to-video(이전 표준 등급, 이 가이드 참고): 초당 더 저렴하고($0.0114–$0.0214/s) Motion Modes를 제공하지만 최대 720p까지만 지원하며 6–30초 길이를 요구합니다. 6초 미만의 클립은 생성할 수 없습니다.

따라서 여기서 "lite"는 초당 가장 저렴한 선택이 아닙니다. 1080P와 아주 짧은 클립을 가능하게 해주는 등급입니다. 단일 정적 이미지를 텍스트 대신 입력하려면 같은 등급의 grok-imagine-1.5-lite/image-to-video 엔드포인트를 사용하세요(가격 동일, 입력은 image_urls).

6. 관련 링크

자주 묻는 질문

폴링해야 하나요, 아니면 콜백이 있나요? 둘 다 가능합니다. 스크립트는 GET /v1/tasks/{taskId}로 폴링하고, 서버는 callback.url을 첨부하고 when을 "final"로 설정합니다. taskId로 중복 제거하세요.

왜 요청이 400과 함께 "must be a JSON object"라고 나오나요? 필드가 input으로 감싸지지 않았기 때문입니다. 요청 본문은 {"model": "...", "input": { ... }} 형태여야 합니다.

오디오를 끌 수 있나요? 요청 시에는 불가능합니다. 모든 출력에 AAC 오디오 트랙이 믹스되어 포함됩니다. 무음이 필요하면 다운스트림에서 ffmpeg -an으로 제거하세요.

출력 URL은 얼마나 유효한가요? expireAt(약 7일)이 있는 임시 URL입니다. 즉시 다운로드하거나 영구 스토리지로 전송하세요. 핫링크하지 마세요.

가장 저렴한 유효 요청은 무엇인가요? 480P에서 1초는 약 $0.029입니다. 대량 처리 전에 키에 잔액이 있는지 확인하는 카나리 요청으로 사용하기 좋습니다.

핵심 요점

필드는 input 아래에 중첩됩니다. 평면 요청 본문은 "invalid input: must be a JSON object"를 반환합니다.
스키마는 폐쇄형이며 실시간 검증되었습니다: prompt(필수), duration(정수 1-15), resolution 480p/720p/1080p, aspect_ratio는 "auto"가 없는 7개 값 열거형입니다.
테스트 기준 출력 초 단위로 과금됩니다: 480P $0.029/s, 720P $0.043/s, 1080P $0.20/s. duration에 의해서만 과금됩니다.
모든 출력에 AAC 오디오 트랙이 믹스되어 포함됩니다. 이를 비활성화하는 스위치는 없습니다(무음이 필요하면 ffmpeg -an 사용).
출력 URL은 임시입니다(storage:temp, 약 7일 expireAt). 즉시 다운로드하거나 영구 스토리지로 전송하세요.
"Lite"는 가장 저렴한 등급이 아닙니다. 초당 요금은 이전 표준 grok-imagine t2v보다 비싸지만, 1080P와 6초 미만의 클립을 추가로 지원합니다.