Grok Imagine 1.0 비디오 생성 API: 엔드포인트, 인증 범위, 오류 처리
대상 모델:
grok-imagine-video-official,grok-imagine-video-1.5-official
추론 엔드포인트:https://api.toapis.com/v1/videos/generations
관련 글: Grok Video 실습 가이드 · OpenAI 호환 접근 · 공식 Imagine 생성 · 공식 Imagine 연장
1. 핵심 요약 및 개요 (TL;DR)
- ID: “Grok Imagine 1.0”이라는 제목이어도 사용 문자열은 ToAPIs가 실제로 공개한 것이어야 합니다. 2026-11-10자 공개 카탈로그 스냅샷은
grok-imagine-video-official과grok-imagine-video-1.5-official을 나열합니다(둘 다 image-generation과openai-video에 나타납니다). 2026-11-17에grok-imagine-1.0문서 경로를 확인한 결과는 HTTP 404였습니다. - 인증:
Authorization: Bearer $TOAPIS_API_KEY를 보내세요. 공식 페이지는 이 호출을 위한 OAuth 범위, 세분 권한 이름, 범위 검색 엔드포인트를 문서화하지 않습니다. - 엔드포인트: 생성은
POST /v1/videos/generations, 폴링은GET /v1/videos/generations/{id}입니다. 공식 채널 출력 연장은POST /v1/videos/{video_id}/extend이고, 공개 비디오 URL만 있으면POST /v1/videos/extend에video_urls를 붙입니다. 정지 이미지 업로드는POST /v1/uploads/images입니다. - 능력:
grok-imagine-video-official은 텍스트-투-비디오, 이미지-투-비디오, 다중 참조를 다루며 해상도는480p또는720p, 길이는 1–15초, 연장은 2–10초입니다.grok-imagine-video-1.5-official은 첫 프레임 이미지-투-비디오만 지원하고image정확히 1장이 필요하며1080p를 허용하고 연장은 지원하지 않습니다. - 과금 형태(레퍼런스 페이지에 고정 단가 없음): 출력은 해상도 구간별 초 과금, 입력 이미지는 장당 과금, 연장은 원본 비디오 길이도 과금합니다. 실시간 계정 요율을 확인하세요.
2. 엔드포인트, 인증, 모델 계약
공식 문서는 https://toapis.com(중국 본토는 https://toapis.cn)을 사용합니다. 이 시리즈의 다른 가이드는 https://api.toapis.com을 사용합니다. 오리진은 하나만 골라 일관되게 쓰세요. 아래 경로는 모두 같은 Bearer 헤더를 사용합니다.
| 작업 | 메서드와 경로 | 모델 참고 |
|---|---|---|
| 정지 이미지 업로드 | POST /v1/uploads/images | Multipart file. JPEG, PNG, WebP 또는 GIF, 최대 30 MB. data.url을 읽기 |
| 비디오 생성 | POST /v1/videos/generations | 두 공식 Imagine ID 모두 |
| 상태 조회 | GET /v1/videos/generations/{id} | 생성과 연장 작업에 같은 경로 |
| 이전 작업에서 연장 | POST /v1/videos/{video_id}/extend | grok-imagine-video-official만. video_id는 이전 생성 작업 id |
| 공개 URL에서 연장 | POST /v1/videos/extend | 같은 공식 ID. 경로 id가 없으면 video_urls가 필수 |
| 카탈로그 ID | 문서화된 작업 | 길이 | 해상도 | 이미지 | 연장 |
|---|---|---|---|---|---|
grok-imagine-video-official | 텍스트-투-비디오, 첫 프레임, 다중 참조 | 1–15초(기본값 8) | 480p, 720p | 선택적 image와 reference_images. 합계 최대 7장 | 2–10초(duration 기본값 6) |
grok-imagine-video-1.5-official | 첫 프레임 이미지-투-비디오만 | 1–15초(기본값 8) | 480p, 720p, 1080p | image는 필수(첫 프레임 정확히 1장). 추가 reference_images도 7장 한도에 포함 | 미지원 |
공식 Imagine 레퍼런스의 화면비에는 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 1:1이 포함됩니다. 해당 ID와 채널에서 확인한 값을 보내세요.
“생성”, “연장”, “업로드”를 따로 요청하는 공개 범위 문자열은 문서화되어 있지 않습니다. 접근 권한은 API 키, 사용자 그룹, 채널 설정이 이미 허용한 범위입니다. 권한이나 가용성으로 실패하면 임의 scope 쿼리를 붙이지 말고 키의 모델 목록과 오류 레퍼런스를 확인하세요.

그림 1: Bearer API 키 하나로 업로드, 생성 또는 연장, 상태 폴링을 인가합니다. 공식 1.5 ID에는 연장 분기가 없습니다.
비공식 Grok Video 계열(grok-video-1.0 / grok-video-1.5)은 Grok Video 실습 가이드를 보세요. 그 ID는 다른 계약이며 이 연장 경로를 상속하지 않습니다.
3. 프로덕션 구현: cURL과 Python
단계 1: cURL — 공식 채널 텍스트-투-비디오
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-official",
"prompt": "A golden retriever running on a green field in sunny weather",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
grok-imagine-video-1.5-official의 첫 프레임 작업은 같은 경로를 사용하고 "image": "https://example.com/portrait.jpg"가 필수이며 "resolution": "1080p"를 지정할 수 있습니다. 예시 URL은 접근 가능한 공개 주소로 바꾸세요. 파일이 로컬이면 먼저 업로드합니다.
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@/path/to/first-frame.jpg"
단계 2: Python — 생성, 폴링, 선택적 연장
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_imagine(
prompt: str,
*,
model: str = "grok-imagine-video-official",
duration: int = 10,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-imagine-video-1.5-official" and not image_url:
raise ValueError("grok-imagine-video-1.5-official requires exactly one first-frame image")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if image_url:
payload["image"] = image_url
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(
f"{BASE}/v1/videos/generations",
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) -> dict:
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={"Authorization": f"Bearer {API_KEY}"}, 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
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")
def extend_official(source_task_id: str, prompt: str, duration: int = 6) -> str:
if not (2 <= duration <= 10):
raise ValueError("official extend duration is documented as 2-10 seconds")
res = requests.post(
f"{BASE}/v1/videos/{source_task_id}/extend",
headers=HEADERS,
json={
"model": "grok-imagine-video-official",
"prompt": prompt,
"duration": duration,
},
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 extend envelope: {data}")
return task_id
if __name__ == "__main__":
task_id = dispatch_imagine(
"A golden retriever running on a green field in sunny weather",
duration=10,
resolution="720p",
)
print("Task:", task_id)
result = poll_task(task_id)
print("Video:", result["result"]["data"][0]["url"])
작업 id가 아니라 공개 MP4에서 연장하려면 같은 공식 모델, 프롬프트, duration, video_urls 목록을 POST /v1/videos/extend로 보내세요. grok-imagine-video-1.5-official로 연장을 호출하지 마세요.
4. 오류 처리 및 상태 매트릭스
아래 표는 진단 출발점이며 ToAPIs 오류 코드와 완전히 일치한다고 보장하지 않습니다. HTTP 조회가 성공해도 작업 status를 읽어야 합니다. 오류 레퍼런스는 요청 오류, 실패 작업의 error.reason, 웹훅 페이로드를 구분합니다.
| HTTP 또는 작업 상태 | 흔한 분류 | 권장 조치 |
|---|---|---|
400 | 잘못된 필드, 1.5-official에서 필수 image 누락, 이미지 수 초과, 연장을 지원하지 않는 모델에 연장 요청 | 정확한 공식 ID, 길이(생성 1–15초, 연장 2–10초), 해상도(1080p는 1.5-official만), 모든 미디어가 공개 URL인지 확인 |
401 | API 키 누락 또는 무효 | 키를 교체하고 Authorization: Bearer를 확인. 문서화되지 않은 scope 파라미터를 우회로 쓰지 말 것 |
429 | 속도 또는 동시성 제한 | Retry-After가 있으면 따르고 지터와 함께 백오프 |
5xx 또는 클라이언트 시간 초과 | 게이트웨이 또는 업스트림 일시 문제 | 재제출 전에 기존 작업 id를 조회 |
status: queued 또는 in_progress | 오류가 아님 | 기다렸다가 다시 폴링 |
status: failed이며 content_policy_rejected | 안전 또는 저작권 심사 | 프롬프트와 모든 참조 자산을 점검. 적합한 입력도 거부된 출력을 낼 수 있음 |
status: failed이며 insufficient_user_balance 또는 token_quota_exceeded | 잔액 또는 토큰 한도 | 잔액과 주기적 한도를 모두 확인 |
status: failed이며 generation_timeout, model_unavailable, service_busy | 업스트림 시간 초과 또는 가용성 | 기존 id를 먼저 확인한 뒤, 작업이 종료된 후에만 백오프로 재시도 |
5. 요금과 FinOps ROI
공식 Imagine 생성 및 연장 페이지가 설명하는 것은 고정 공개 단가가 아니라 과금 형태입니다.
초안 숫자가 아니라 계정과 SKU가 반환하는 요율을 사용하세요.
grok-imagine-video-1.5-official에는 항상 입력 이미지 요금이 한 번 포함됩니다. 첫 프레임 이미지가 필수이기 때문입니다.- 연장은 무료 이어쓰기가 아닙니다. 공식 연장 과금은 생성된 연장 초와 함께 원본 비디오 길이를 포함합니다. 연장을 겹치면 길어지는 원본을 다시 과금합니다. 루프를 만들기 전에 실시간 견적으로 이 동작을 확인하세요.
- 기획 초안의 단가나 SLA 수치를 재사용하지 마세요. ToAPIs 요금 페이지의 공식 벤더 참고 행은 표시용이며 계정 청구와 다를 수 있습니다.
720p와 중간 길이로 초안을 만들고, 한 번에 변수 하나만 바꾸며, 클라이언트 시간 초과 후에는 상태를 확인하기 전에 재제출하지 마세요.
6. 자주 묻는 질문
frontmatter의 FAQ를 보세요. 요약: grok-imagine-1.0이 아니라 grok-imagine-video-official 또는 grok-imagine-video-1.5-official을 보내고, 인증은 공개 OAuth 범위 행렬이 없는 Bearer API 키이며, 1.5-official은 첫 프레임만 지원하고 연장할 수 없고, 연장 길이는 2–10초이며 원본 길이도 과금되고, HTTP 오류와 status: failed는 반드시 구분하세요.
7. 액션 체크리스트
- ToAPIs 개발자 포털에서 키를 만듭니다.
-
GET /v1/models?type=video로 키에grok-imagine-video-official또는grok-imagine-video-1.5-official이 보이는지 확인합니다. -
720p공식 채널 생성을 스모크 테스트하고GET /v1/videos/generations/{id}를 폴링한 뒤expires_at전에 파일을 다운로드합니다. - 이어쓰기가 필요하면
grok-imagine-video-official과 2–10초duration으로만 연장하고, 견적에 원본 길이 과금이 포함되는지 확인합니다. - 다음: 현재 카탈로그는 공식 Imagine 모델 가이드와 공식 Imagine 1.5 모델 가이드. 실제로 필요한 것이 비공식
grok-video-*계열이면 Grok Video 실습 가이드를 읽으세요.







