Grok-Video-3 API 실습 가이드: xAI 비디오 엔진에서 먼저 확인해야 할 현재 계약
대상 모델:
grok-video-1.5,grok-video-1.0
추론 엔드포인트:https://api.toapis.com/v1/videos/generations
관련 글: OpenAI 호환 접근 · Grok Imagine 공식 채널 API · Hailuo 2.3 비디오 가이드 · Grok Video 1.5 레퍼런스
1. 핵심 요약 및 개요 (TL;DR)
- 카탈로그부터: Grok Video 3 실습이라도 호출은 ToAPIs가 실제로 공개한 ID에서 시작해야 합니다. 2026-11-10자 공개 프로덕션 카탈로그 스냅샷은
openai-video엔드포인트에grok-video-1.0과grok-video-1.5를 나열합니다. 2026-11-17에grok-video-3문서와 모델 가이드 URL을 확인한 결과는 HTTP 404였습니다. - 계약:
POST /v1/videos/generations에 비동기로 제출한 뒤GET /v1/videos/generations/{id}를completed또는failed까지 폴링합니다. 공식 예시는https://toapis.com(중국 본토는https://toapis.cn)입니다. 이 시리즈의 다른 가이드는https://api.toapis.com을 사용합니다. 오리진은 하나만 골라 일관되게 쓰세요. - 모드:
grok-video-1.5는text_to_video,first_frame_image_to_video,reference_images_to_video를 문서화합니다.video_generation_mode를 명시해 참조 이미지 한 장이 레거시 첫 프레임 작업으로 처리되지 않게 하세요. - 미디어: 공개
http://또는https://URL만 보내세요. 로컬 파일은POST /v1/uploads/images로 업로드하고 반환된data.url을 사용하세요. base64는 보내지 마세요. - 버려야 할 미검증 주장: 기획 초안의
grok-video-3ID, 99.95% SLA, 고정$0.030–$0.038초당 요율, 미래 오디오 출시일은 현재 ToAPIs 문서가 아닙니다. 실시간 요율과 채널 지원은 계정에서 확인하세요.
2. 현재 Grok Video ID와 생성 모드
model 필드에는 공개 모델 이름을 사용하세요. 공급자 고유 이름, URL 슬러그, 미공개 grok-video-3 문자열로 바꾸지 마세요.
| 카탈로그 ID | 문서화된 작업 | 길이(문서) | 해상도 | 이미지 입력 |
|---|---|---|---|---|
grok-video-1.5 | 텍스트, 첫 프레임, 또는 1–7장 참조 이미지. video_generation_mode로 지정 | 정수 1–15초 | 참조 모드는 480p 또는 720p. 텍스트와 첫 프레임은 채널이 지원하면 1080p | 첫 프레임: image 또는 input_reference로 정확히 1장. 참조 모드: 1–7장의 reference_images |
grok-video-1.0 | 텍스트-투-비디오와 이미지-투-비디오 | 생성 레퍼런스: 1–15초(기본값 8). 모델 가이드 / Playground: 현재 사용 가능한 변형은 6초 상한 | 480p, 720p | 선택적 image와 reference_images. 합계 최대 8장 |
grok-video-1.5의 새 연동은 모드를 명시하세요.
video_generation_mode | 필수 입력 | 생략해야 할 것 |
|---|---|---|
text_to_video | 비어 있지 않은 prompt | 모든 이미지 필드 |
first_frame_image_to_video | image 또는 input_reference에 첫 프레임 정확히 1장 | 두 별칭에 서로 다른 값을 넣지 말 것. 계정 레퍼런스가 달리 말하지 않으면 참조 목록을 함께 보내지 말 것 |
reference_images_to_video | prompt와 1–7장의 reference_images(문자열 또는 {"url":"..."} 객체) | 이 모드 없이 reference_images 한 장만 보내는 것. 레거시 단일 이미지 입력은 첫 프레임 동작으로 남습니다 |
견적 성공이 생성 채널이 열려 있다는 보장은 아닙니다. 모드는 호환 채널에서 켜진 뒤에만 사용할 수 있으며, 지원되지 않는 조합은 작업 생성 전에 거부될 수 있습니다.
Grok Video 레퍼런스의 일반적인 화면비는 16:9, 9:16, 3:2, 2:3, 1:1입니다. 사용 가능 여부는 채널에 따라 다르므로 해당 ID에서 확인한 값을 보내세요.

그림 1: 프롬프트(와 선택적 공개 이미지 URL)를 POST /v1/videos/generations에 제출하고, 같은 작업 id를 폴링한 뒤, status가 completed일 때만 result.data[0].url을 읽습니다.
공식 채널 Grok Imagine의 비디오 연장 등이 필요하면 다른 ID 계열입니다. Imagine 공식 채널 가이드를 보세요. 다른 길이 체계의 두 번째 비디오 계약은 Hailuo 2.3 가이드를 참고하세요.
3. 프로덕션 구현: cURL과 Python
이 시리즈의 국제 예시는 https://api.toapis.com을 사용합니다. 공식 문서는 중국 본토 사용자에게 https://toapis.cn을 안내합니다. 환경마다 오리진은 하나만 유지하세요. 경로, 모델 ID, Bearer 헤더는 같습니다.
단계 1: cURL로 grok-video-1.5 제출하기
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-video-1.5",
"prompt": "A cinematic product shot with a slow camera push-in",
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
첫 프레임 작업은 같은 경로에 "video_generation_mode": "first_frame_image_to_video"와 image URL을 사용합니다. 참조 이미지 작업은 "video_generation_mode": "reference_images_to_video"와 reference_images 목록을 설정하고 resolution은 480p 또는 720p로 유지합니다.
단계 2: Python 제출 및 폴링 도우미
아래 예시는 문서화된 작업 상태 경로와 queued / in_progress / completed / failed 상태를 따릅니다. 배포 전에 계정 API 레퍼런스에서 id, result.data[0].url, 응답 구조를 확인하세요.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_grok_video(
prompt: str,
*,
model: str = "grok-video-1.5",
mode: str = "text_to_video",
duration: int = 8,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-video-3":
raise ValueError("grok-video-3 is not a current public catalog ID")
if mode == "reference_images_to_video" and resolution not in {"480p", "720p"}:
raise ValueError("reference mode is documented as 480p or 720p")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if model == "grok-video-1.5":
payload["video_generation_mode"] = mode
if mode == "text_to_video" and (image_url or reference_images):
raise ValueError("text_to_video rejects image fields")
if mode == "first_frame_image_to_video":
if not image_url:
raise ValueError("first-frame mode requires exactly one image URL")
payload["image"] = image_url
if mode == "reference_images_to_video":
refs = reference_images or []
if not (1 <= len(refs) <= 7):
raise ValueError("reference mode requires 1-7 image URLs")
payload["reference_images"] = refs
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_grok_video(
"A cinematic product shot with a slow camera push-in",
mode="text_to_video",
duration=8,
resolution="720p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
프롬프트 템플릿 버전을 작업 기록과 함께 저장해 모델·모드 변경과 문구 변경을 구분하세요. expires_at 전에 파일을 다운로드하세요. 상태 레퍼런스는 30일 보관 기간을 문서화합니다.
4. 오류 처리 및 상태 매트릭스
아래 표는 진단 출발점이며 ToAPIs 오류 코드와 완전히 일치한다고 보장하지 않습니다. HTTP 조회가 성공해도 작업 status를 읽어야 합니다. 요청 오류와 status: failed 이유(content_policy_rejected, insufficient_user_balance, generation_timeout 등)는 오류 레퍼런스를 보세요.
| HTTP 또는 작업 상태 | 흔한 분류 | 권장 조치 |
|---|---|---|
400 | 잘못된 필드, 모드/미디어 불일치, 지원되지 않는 조합 | 정확한 카탈로그 ID, video_generation_mode가 이미지 필드와 일치하는지, 참조 모드가 480p 또는 720p인지, 이미지 값이 공개 URL인지 확인 |
401 | API 키 누락 또는 무효 | ToAPIs 대시보드에서 키를 교체하고 Authorization: Bearer 헤더를 확인 |
429 | 속도 또는 동시성 제한 | Retry-After가 있으면 따르고, 지터와 함께 백오프하며, 안전할 때만 재시도 |
5xx 또는 클라이언트 시간 초과 | 게이트웨이 또는 업스트림 일시 문제 | 재제출 전에 기존 작업 id를 조회 |
status: queued 또는 in_progress | 오류가 아님 | 기다렸다가 다시 폴링. 두 번째 작업을 만들지 말 것 |
status: failed | 생성이 성공하지 않음 | error.code와 error.message(있으면 error.reason)를 읽기. 정책으로 거부된 본문을 그대로 재시도하지 말 것 |
5. 요금과 FinOps ROI
- 기획 초안 단가를 재사용하지 마세요.
grok-video-1.5API 레퍼런스는 요금이 현재 계정과 SKU 설정을 따르며, 해당 페이지가 고정 초당 가격을 보장하지 않는다고 명시합니다. ToAPIs 요금 페이지의 공식 벤더 참고 행은 표시용이며 계정 청구와 다를 수 있습니다. - 견적은 채널 보장이 아닙니다. 1.5 레퍼런스는 견적 성공이 생성 채널 가용성을 의미하지 않는다고 적습니다.
- 프롬프트 계층에서 지출을 제어하세요.
720p와 8초 전후 중간 길이로 초안을 만들고, 버전 관리된 템플릿을 유지하며, 한 번에 변수 하나만 바꾸고, 클라이언트 시간 초과 후에는 상태를 확인한 뒤에만 재제출하세요. - 공식 벤더 계약에는 연간 약정, 좌석 할당, 선불 하한이 붙는 경우가 많습니다. ToAPIs 과금은 보통 사용량 기준입니다. 계정의 현재 조건을 확인하세요.
6. 자주 묻는 질문
frontmatter의 FAQ를 보세요. 요약: grok-video-3는 현재 공개 카탈로그 ID가 아닙니다. grok-video-1.5 또는 grok-video-1.0으로 시작하고, 1.0 길이 상한은 채널별 확인 사항이며, 동기 오디오는 문서화되어 있지 않고, 항상 generations 상태 경로를 폴링하고 작업 id를 저장하세요.
7. 액션 체크리스트
- ToAPIs 개발자 포털에서 키를 만듭니다.
-
GET /v1/models?type=video로 키에grok-video-1.5또는grok-video-1.0이 보이는지 확인합니다. 목록과 API 레퍼런스에 나중에 나타나지 않는 한grok-video-3를 보내지 마세요. -
video_generation_mode: "text_to_video",duration: 8,resolution: "720p"로 위 cURL을 스모크 테스트합니다. - 기한을 두고
GET /v1/videos/generations/{id}를 폴링하고expires_at전에 결과를 다운로드합니다. - 다음: 기존 클라이언트를 ToAPIs로 향하게 하려면 OpenAI 호환 접근 가이드, 현재 카탈로그는 Grok Video 1.5 모델 가이드. 1.0에서 6초를 넘는 길이에 의존하기 전에 Grok Video 1.0 모델 가이드를 확인하세요.







