OpenAI 호환 엔드포인트로 Grok Video 3 API에 접근하기
대상 모델:
grok-video-1.5,grok-video-1.0
추론 엔드포인트:https://api.toapis.com/v1/videos/generations
관련 글: Grok Video 실습 가이드 · Grok Imagine 공식 채널 API · Chatbox OpenAI 호환 설정 · 모델 목록
1. 핵심 요약 및 개요 (TL;DR)
- 여기서 말하는 “OpenAI 호환”: ToAPIs는 단일
/v1오리진, Bearer 인증, OpenAI 스타일 모델 목록과 채팅 완성 API를 문서화합니다. 공개 Grok Video ID는 카탈로그의openai-video엔드포인트 계열에 등록되어 있습니다. 이것이 미공개grok-video-3가 동작한다는 뜻도, OpenAI Videos SDK 메서드가 문서화되었다는 뜻도 아닙니다. - ID:
GET /v1/models?type=video에서 키에 보인 뒤에grok-video-1.5또는grok-video-1.0을 사용하세요. 2026-11-10자 공개 카탈로그 스냅샷에는grok-video-3가 없습니다. - 비디오 경로: 생성은
POST /v1/videos/generations, 폴링은GET /v1/videos/generations/{id}입니다. 공식 예시는https://toapis.com(중국 본토는https://toapis.cn)입니다. 이 시리즈는https://api.toapis.com도 사용합니다. - 공유 인증:
Authorization: Bearer에 API 키 하나를 사용합니다. 이 비디오 호출을 위한 별도의 공개 OAuth 범위 문서는 없습니다. - 클라이언트 선택: 채팅과 익숙한 키/오리진 설정에는 OpenAI SDK의
base_url="https://api.toapis.com/v1"를 쓸 수 있습니다. Grok Video에서는video_generation_mode와 이미지 URL 필드를 명시하기 위해 문서화된 REST JSON 본문을 사용합니다.
2. 호환 오리진, 모델 목록, 비디오 경로
오리진, /v1 접두사, 키는 함께 사용하세요. ToAPIs 키를 https://api.openai.com/v1과 섞거나, ToAPIs 오리진을 공급자 고유 Grok 경로와 조합하는 것은 다른 — 그리고 문서화되지 않은 — 구성입니다.
| 단계 | 문서화된 경로 | 참고 |
|---|---|---|
| 모델 목록 | GET /v1/models?type=video | 기본 GET /v1/models는 텍스트 모델만 반환합니다. type=video 또는 type=all을 사용하세요 |
| 로컬 이미지 업로드 | POST /v1/uploads/images(multipart file) | data.url을 읽으세요. 생성 호출에 base64를 보내지 마세요 |
| Grok Video 작업 생성 | POST /v1/videos/generations | 본문에 model, prompt, 1.5 모드/미디어 필드가 들어갑니다 |
| 상태 폴링 | GET /v1/videos/generations/{id} | 종료 상태는 completed와 failed입니다 |
| 채팅(비디오 아님) | POST /v1/chat/completions | 오리진과 키만 공유합니다 |
grok-video-1.5에서는 보내는 미디어에 맞게 video_generation_mode를 text_to_video, first_frame_image_to_video, 또는 reference_images_to_video로 설정하세요. 필드 계약은 Grok Video 실습 가이드와 Grok Video 1.5 API 레퍼런스를 보세요.

그림 1: 클라이언트를 ToAPIs /v1 오리진으로 향하게 하고, 모델 목록에서 grok-video-1.5 또는 grok-video-1.0을 확인한 다음 /v1/videos/generations에서 제출하고 폴링하세요. chat/completions는 사용하지 않습니다.
애플리케이션 코드가 아니라 데스크톱 클라이언트를 설정한다면 Chatbox 설정 가이드가 채팅용 호스트 필드 패턴을 다룹니다. 같은 채팅 경로가 비디오 파일을 반환할 것으로 기대하지 마세요.
3. 프로덕션 구현: cURL과 Python
이 시리즈의 국제 예시는 https://api.toapis.com을 사용합니다. 공식 문서는 중국 본토 사용자에게 https://toapis.cn을 안내합니다. 환경마다 오리진은 하나만 유지하세요.
단계 1: ID를 확인한 뒤 cURL로 제출하기
curl -sS "https://api.toapis.com/v1/models?type=video" \
-H "Authorization: Bearer $TOAPIS_API_KEY"
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"
}'
하드코딩하기 전에 모델 목록의 정확한 id 문자열을 확인하세요. grok-video-3가 없으면 보내지 마세요.
단계 2: Python — 오리진은 공유하고, 비디오는 REST로 호출
여기 OpenAI SDK는 공유 base_url과 API 키만을 위해 보여 줍니다. 비디오 생성과 폴링은 비공식 클라이언트 매핑에서 1.5 본문 필드가 빠지지 않도록 문서화된 generations 경로를 유지합니다.
import os
import time
import requests
from openai import OpenAI
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
# Shared origin and key. Use this client for chat completions; do not assume
# a videos.create mapping unless your account docs define one.
client = OpenAI(base_url=f"{BASE}/v1", api_key=API_KEY)
def list_video_model_ids() -> list[str]:
res = requests.get(
f"{BASE}/v1/models",
headers=HEADERS,
params={"type": "video"},
timeout=30,
)
res.raise_for_status()
data = res.json()
items = data.get("data") or data.get("models") or []
return [item.get("id") or item.get("name") for item in items if item]
def dispatch_grok_video(prompt: str, model: str = "grok-video-1.5") -> str:
available = set(list_video_model_ids())
if available and model not in available:
raise ValueError(f"{model} is not in this key's video model list")
res = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json={
"model": model,
"prompt": prompt,
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
},
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__":
print("Video models (excerpt):", list_video_model_ids()[:20])
task_id = dispatch_grok_video("A cinematic product shot with a slow camera push-in")
print("Task:", task_id)
print("Video:", poll_task(task_id))
목록 응답 구조가 예상과 다르면 원본 JSON을 기록하고 계정의 모델 목록 페이지에 맞춰 파서를 조정하세요. ID가 없을 때 grok-video-3를 보내는 폴백을 만들지 마세요.
4. 오류 처리 및 상태 매트릭스
아래 표는 진단 출발점이며 ToAPIs 오류 코드와 완전히 일치한다고 보장하지 않습니다. HTTP 조회가 성공해도 작업 status를 읽어야 합니다. 오류 레퍼런스를 보세요.
| HTTP 또는 작업 상태 | 흔한 분류 | 권장 조치 |
|---|---|---|
400 | 알 수 없는 모델 ID, 모드/미디어 불일치, 또는 비디오 본문을 채팅 경로로 보냄 | GET /v1/models?type=video로 ID를 확인하고, /v1/videos/generations에 POST했는지, 1.5 작업에 일치하는 video_generation_mode가 있는지 확인 |
401 | API 키 누락 또는 무효 | OpenAI 플랫폼 키가 아니라 ToAPIs 키를 쓰고 Bearer 헤더를 확인 |
404 | 잘못된 오리진, /v1 누락, 또는 /videos/tasks/{id} 같은 임의 경로 | 제출에 사용한 같은 오리진에서 GET /v1/videos/generations/{id}로 전환 |
429 | 속도 또는 동시성 제한 | Retry-After가 있으면 따르고 지터와 함께 백오프 |
5xx 또는 클라이언트 시간 초과 | 게이트웨이 또는 업스트림 일시 문제 | 재제출 전에 기존 작업 id를 조회 |
status: failed | 생성이 성공하지 않음 | error.code와 error.message를 읽기. 정책으로 거부된 본문을 그대로 재시도하지 말 것 |
5. 요금과 FinOps ROI
- 호환성이 과금 SKU를 바꾸지는 않습니다. 청구 대상은 전송한 카탈로그 모델 ID(
grok-video-1.5또는grok-video-1.0)이지 “OpenAI SDK를 사용했다”는 사실이 아닙니다. - 기획 초안 단가를 재사용하지 마세요. Grok Video 1.5 레퍼런스는 고정 초당 가격을 보장하지 않습니다. ToAPIs 요금 페이지의 공식 벤더 참고 행은 표시용이며 계정 청구와 다를 수 있습니다.
- 검색 비용은 낮고 중복 생성 비용은 높습니다. 모델 목록은 짧게 캐시해도 되지만, 클라이언트 시간 초과 후에는 새 작업을 만들기 전에 반드시 상태를 확인하세요.
- ToAPIs 과금은 보통 사용량 기준입니다. 계정의 현재 조건을 확인하세요.
6. 자주 묻는 질문
frontmatter의 FAQ를 보세요. 요약: 호환 오리진이 grok-video-3를 열어 주지는 않습니다. /v1은 한 번만 넣고, /v1/videos/generations/{id}를 폴링하며, SDK videos.create 도우미를 가정하지 말고, 채팅 완성은 MP4를 반환하지 않습니다.
7. 액션 체크리스트
- ToAPIs 개발자 포털에서 키를 만듭니다.
- 클라이언트를
https://api.toapis.com/v1(중국 본토는https://toapis.cn/v1)로 향하게 하고Authorization: Bearer를 붙입니다. -
GET /v1/models?type=video를 호출해 키에 보이는 정확한 Grok Video ID를 기록합니다. -
grok-video-1.5와video_generation_mode: "text_to_video"로POST /v1/videos/generations를 스모크 테스트한 뒤 같은 id를 폴링합니다. - 다음: 모드와 이미지 필드 세부 사항은 Grok Video 실습 가이드, 현재 카탈로그는 Grok Video 1.5 모델 가이드.







