Grok Imagine Video API: Python으로 텍스트에서 영상 만들기

Grok Imagine Video API는 비동기 API입니다. 프롬프트로 작업을 만들고, 작업 ID를 완료될 때까지 폴링한 뒤 MP4를 내려받습니다. 현재 모델은 grok-imagine-video-1.5입니다. 2026년 10월 24일, 6초 720p 클립은 요청을 보낸 뒤 46초 만에 준비됐고 음성 트랙도 들어 있었습니다.

아래에는 그대로 실행되는 스크립트, 결과를 좌우하는 파라미터, 클립 한 편의 비용과 시간, 실제로 만나게 되는 오류를 정리했습니다.

먼저 결론

• 모델: grok-imagine-video-1.5. xAI는 1.5가 프리뷰를 끝내고 2026년 6월 16일 정식 출시됐다고 합니다(xAI).
• 설정: duration은 4~15초, resolution은 "720p", ratio는 "16:9" 같은 값입니다.
• 비용: xAI 정가로 720p는 초당 0.14달러, 6초 클립은 0.84달러입니다(xAI 모델 페이지, 2026년 10월 24일 확인).
• 시간: 6초 720p 작업은 46초 걸렸습니다. 한 시간 안에 같은 작업 ID를 폴링해 파일을 내려받으세요.

Grok Imagine Video API는 어떻게 동작하나?

작업은 세 단계입니다. 생성, 폴링, 다운로드(xAI 영상 생성 가이드, 2026년 10월 24일 확인).

xAI 자체 API에서는 https://api.x.ai/v1/videos/generations에 모델 ID와 프롬프트를 POST하고 request_id를 받습니다. 그다음 https://api.x.ai/v1/videos/{request_id}를 GET으로 폴링해 작업이 done이 되면 video.url을 읽습니다(같은 가이드).

xAI는 간단한 영상에는 grok-imagine-video-1.5-lite를, 참조 이미지·음성·고정 프레임·네이티브 1080p가 필요할 때는 grok-imagine-video-1.5를 권합니다(영상 개요, 2026년 10월 24일 확인). 정지 이미지는 Grok Imagine 이미지 API 가이드에서 xAI의 이미지 모델 세 가지를 다룹니다. Grok과 다른 영상 API를 비교하려면 영상 모델 정리를 보세요.

OmniaKey는 Grok Imagine Video 1.5의 API 접근을 판매하므로 예제도 OmniaKey로 실행했습니다. 호출은 POST https://api.omniakey.com/v1/media/tasks에 Idempotency-Key 헤더를 붙여 보내고 202와 id를 받습니다. 상태는 GET /v1/media/tasks/{id}로 확인합니다(OmniaKey 미디어 개요, 2026년 10월 24일 확인). 작업 생성, 폴링, 다운로드 흐름은 영상 API 문서의 Kling 3.0, Seedance, Wan 3.0, MiniMax H3, HappyHorse에도 같습니다. 아래 가격은 모두 xAI 자체 가격입니다.

xAI 필드 이름은 Videos API 레퍼런스에서, OmniaKey 필드 이름은 영상 API 문서에서 가져왔고 둘 다 2026년 10월 24일 확인했습니다.

어떤 파라미터를 설정할 수 있나?

프롬프트와 세 가지 설정이 결과를 정합니다.

• duration은 OmniaKey에서 필수이고 가격도 정합니다(OmniaKey 영상 문서). OmniaKey의 이 모델 최소값은 4초, xAI의 최대값은 15초이므로(영상 생성 가이드) 4~15초로 맞추세요.
• resolution은 소문자 "720p"를 보냅니다. OmniaKey의 Grok 영상은 최대 720p입니다(OmniaKey 미디어 개요). xAI 자체 API에는 480p(기본값)와 네이티브 1080p도 있습니다(생성 가이드).
• ratio는 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2 아홉 가지이고 기본값은 16:9입니다(영상 생성 가이드). 우리는 16:9로 실행했습니다.
• n은 1만 됩니다(OmniaKey 영상 문서).
• 프롬프트는 장면, 빛, 카메라 움직임을 쓰고 Sound: 줄을 더합니다. 거기 적은 것은 화면에도 나타날 수 있습니다. 우리는 음성 줄에 숟가락을 적었을 뿐인데 화면에 숟가락과 손이 나타났습니다.

Python으로 텍스트에서 영상을 만드는 방법

requests를 설치하고 키를 OMNIAKEY_API_KEY에 넣은 뒤 스크립트를 실행하세요.

pip install requests
export OMNIAKEY_API_KEY="your-key"

이것이 우리가 실행한 스크립트 그대로입니다:

import os
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

PROMPT = (
    "Close-up of a white ceramic coffee cup on a wooden café table by a window, "
    "morning sunlight, steam curling up from the coffee, the camera slowly pushes in, "
    "shallow depth of field. Sound: quiet café chatter and a spoon clinking on a saucer."
)

# 1. 작업을 만든다. 이 요청을 그대로 재시도할 때만 같은 Idempotency-Key를 쓴다.
job = requests.post(
    API,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "model": "grok-imagine-video-1.5",
        "type": "video",
        "operation": "text_to_video",
        "input": {"prompt": PROMPT},
        "parameters": {"duration": 6, "resolution": "720p", "ratio": "16:9"},
    },
    timeout=30,
)
job.raise_for_status()
task = job.json()
print("task:", task["id"], task["status"])

# 2. 작업이 끝날 때까지 폴링한다. 느린 작업은 실패가 아니다. 같은 id를 계속 묻는다.
while True:
    task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] not in ("queued", "processing"):
        break
    time.sleep(5)

if task["status"] != "succeeded":
    raise SystemExit(f"job ended {task['status']}: {task.get('error')}")

# 3. 지금 내려받는다. 서명된 URL은 약 한 시간 뒤 만료된다.
asset = task["assets"][0]
with open("coffee.mp4", "wb") as f:
    f.write(requests.get(asset["url"], timeout=120).content)
print("saved coffee.mp4", asset["mime_type"], asset["byte_size"], "bytes")

2026년 10월 24일에 실행했을 때 마지막으로 출력된 줄입니다:

saved coffee.mp4 video/mp4 2659230 bytes

스크립트 첫 줄은 작업 ID와 상태를 출력합니다. 이 ID를 기억하세요. 스크립트가 멈추면 이 ID로 작업을 다시 찾습니다.

6초 720p 작업은 이렇게 돌아왔습니다:

클립은 프롬프트를 따릅니다. 흰 세라믹 컵에 담긴 블랙커피, 흰 받침, 창가의 나무 테이블, 피어오르는 김이 있고 뒤쪽 카페는 흐릿합니다. 카메라는 일정하게 다가가고 컵은 화면 폭의 약 3분의 1에서 절반까지 커집니다. 4.5초에 오른쪽에서 숟가락이 들어옵니다. 오디오는 조용한 트랙이고 4.8초에 날카로운 피크가 하나 있는데, 숟가락이 받침에 닿는 순간과 맞습니다.

클립 한 편에 얼마이고 얼마나 걸리나?

xAI는 영상을 초 단위로 과금하고 요율은 모델과 해상도에 따라 다릅니다. 모델 페이지(2026년 10월 24일 확인)에 해상도별 가격이 있고, 가격 페이지의 초당 0.080달러 일괄 요금은 480p 요율입니다.

이 정가로 계산하면:

• 1.5 720p 6초: 6 × 0.14 = 0.84달러.
• 1.5 480p 8초(기본 길이): 8 × 0.08 = 0.64달러.
• 1.5 1080p 15초: 15 × 0.25 = 3.75달러.
• 1.5 Lite 720p 6초: 6 × 0.03 = 0.18달러.

xAI는 초당 영상 요금만 공개합니다(가격 페이지, 2026년 10월 24일 확인).

OmniaKey에서는 요청한 길이에 초당 요율을 곱한 금액이 작업 생성 시 잔액에서 차감되고, 실패한 작업은 자동으로 환불됩니다(OmniaKey 영상 문서, 2026년 10월 24일 확인). 6초를 요청해 6.04초 파일을 받았고 청구는 6초였습니다. 현재 요율은 Grok Imagine Video 1.5 페이지에 있습니다.

이 작업은 요청에서 succeeded까지 46초였습니다. xAI는 생성에 "보통 몇 분이 걸린다"고 하고 자사 SDK는 최대 10분을 기다립니다(생성 가이드). 몇 초마다 폴링하세요. 루프에 마감 시간을 둔다면 넉넉하게 잡고, 넘기면 새 요청을 보내지 말고 작업 ID로 다시 조회하세요.

서명된 링크는 약 한 시간 유효하고, 우리 링크는 작업이 끝난 지 정확히 한 시간 뒤에 만료됐습니다. 작업 기록은 24시간 보관되므로 다시 폴링해 새 링크를 받을 수 있습니다(OmniaKey 미디어 개요, 2026년 10월 24일 확인).

어떤 오류가 나오나?

대부분의 오류는 작업이 만들어지기 전에 돌아오므로 비용이 없습니다. 작업이 만들어진 뒤 실패하면 failed로 끝나고 환불됩니다. OmniaKey 미디어 문서(2026년 10월 24일 확인)에 이런 항목이 있습니다:

2026년 10월 24일 앞의 두 가지를 일부러 냈습니다. 헤더를 빼면 HTTP 400이 돌아옵니다:

{"error":{"code":"missing_idempotency_key","message":"Idempotency-Key is required and must be at most 255 characters"}}

작업의 키를 그대로 두고 프롬프트를 바꿔 보내면 HTTP 409가 돌아옵니다:

{"error":{"code":"idempotency_key_reused","message":"Idempotency-Key was already used with a different request"}}

• 느린 작업은 아직 실행 중으로 보세요. 같은 작업 ID를 계속 폴링합니다. 새 Idempotency-Key로 다시 보내면 두 번째 작업이 시작되고 요금도 두 번 나옵니다.
• 재전송한 요청은 원래 작업과 200을 돌려주지만 assets 목록이 없습니다. 스크립트가 먼저 작업을 조회한 뒤 assets를 읽는 이유입니다.

자주 묻는 질문

Grok Imagine Video API는 무료인가요?

아니요. xAI는 초당 요금만 공개하고 가장 싼 것은 1.5 Lite 480p로 초당 0.02달러입니다(모델 페이지, 2026년 10월 24일 확인).

Grok Imagine 영상은 몇 초까지 만들 수 있나요?

xAI API에서는 115초이고 기본은 8초입니다(영상 생성 가이드). OmniaKey로는 415초를 쓰세요. OmniaKey의 이 모델 최소값이 4초이고(OmniaKey 영상 문서, 2026년 10월 24일 확인) xAI 최대값이 15초입니다.

Grok Imagine Video는 소리가 나나요?

네, 기본으로 오디오 트랙이 붙고 효과음, 환경음, 대사가 화면과 함께 생성됩니다(영상 생성 가이드; xAI 발표). 우리 클립에는 스테레오 AAC 트랙이 있었습니다. xAI API에서는 generate_audio: false로 무음 클립을 받습니다. 내려받은 파일에서 트랙을 빼려면 다음을 실행하세요:

ffmpeg -i coffee.mp4 -an -c:v copy coffee-silent.mp4

Grok Imagine으로 이미지를 영상으로 만들 수 있나요?

됩니다. xAI API에서는 image로 넘깁니다(공개 URL, base64 data URI, Files API의 file_id 중 하나. JPEG, PNG, WebP). 그 이미지가 첫 프레임이 되고 프롬프트는 생략할 수 있으며 클립은 이미지의 화면 비율을 따릅니다(이미지에서 영상 가이드; Videos API 레퍼런스). OmniaKey를 거치는 이미지에서 영상 예제는 처음부터 끝까지 확인한 뒤 여기에 추가하겠습니다.

Grok Imagine Video 1.5와 1.5 Lite의 차이는?

Lite는 초당 가격이 가장 쌉니다. 텍스트에서 영상, 이미지에서 영상을 지원하고 입모양이 맞는 음성이 붙으며 1080p는 720p를 업스케일해 만듭니다. 참조 이미지, 음성 참조, 키프레임은 없습니다(영상 개요; Lite 모델 페이지). 여기 예제는 1.5를 쓰며 OmniaKey에서는 Grok Imagine Video 1.5로 호출합니다.

grok-imagine-video-1.5-preview도 아직 쓸 수 있나요?

xAI는 아직 별칭으로 올려 두었지만 1.5는 프리뷰를 끝내고 2026년 6월 16일 정식 출시됐습니다(모델 페이지; xAI 발표). grok-imagine-video-1.5를 쓰세요.