Практическое руководство по Grok-Video-3 API: что нужно знать о текущем контракте видеодвижка xAI
Целевые модели:
grok-video-1.5,grok-video-1.0
Эндпоинт инференса:https://api.toapis.com/v1/videos/generations
Связанные материалы: OpenAI-совместимый доступ · Официальный канал Grok Imagine · Руководство по Hailuo 2.3 · Справочник Grok Video 1.5
1. Краткое содержание и обзор (TL;DR)
- Сначала каталог: даже практическая статья про Grok Video 3 должна начинаться с идентификаторов, которые ToAPIs действительно публикует. Снимок публичного производственного каталога от 2026-11-10 перечисляет
grok-video-1.0иgrok-video-1.5на эндпоинтеopenai-video. Проверка URL документации и model-guide дляgrok-video-32026-11-17 вернула HTTP 404. - Контракт: отправляйте задания асинхронно на
POST /v1/videos/generations, затем опрашивайтеGET /v1/videos/generations/{id}доcompletedилиfailed. Официальные примеры используютhttps://toapis.com(иhttps://toapis.cnдля материкового Китая). Другие руководства этой серии используютhttps://api.toapis.com. Выберите один origin и придерживайтесь его. - Режимы:
grok-video-1.5документируетtext_to_video,first_frame_image_to_videoиreference_images_to_video. Явно задавайтеvideo_generation_mode, чтобы одно референсное изображение не обрабатывалось как устаревшее first-frame задание. - Медиа: отправляйте только публичные URL
http://илиhttps://. Локальные файлы загружайте черезPOST /v1/uploads/imagesи используйте возвращённыйdata.url. Не отправляйте base64. - Непроверенные утверждения, которые нужно отбросить: черновики планирования с ID
grok-video-3, SLA 99,95%, фиксированной ценой$0.030–$0.038за секунду или датой появления звука не являются текущей документацией ToAPIs. Живые тарифы и доступность канала подтверждайте в аккаунте.
2. Текущие идентификаторы Grok Video и режимы генерации
В поле model используйте публичное имя модели. Не подменяйте его именем поставщика, URL-slug или неопубликованной строкой grok-video-3.
| ID каталога | Документированные задачи | Длительность (документы) | Разрешение | Входные изображения |
|---|---|---|---|---|
grok-video-1.5 | Текст, первый кадр или 1–7 референсов, выбирается через video_generation_mode | Целое число 1–15 секунд | 480p или 720p в режиме референсов; текст и first-frame могут использовать 1080p, если канал поддерживает | Первый кадр: ровно одно значение в image или input_reference. Режим референсов: 1–7 reference_images |
grok-video-1.0 | Text-to-video и image-to-video | Справочник генерации: 1–15 секунд (по умолчанию 8). Model-guide / 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 | Противоречивые значения в обоих псевдонимах; не добавляйте список референсов, пока справочник вашего аккаунта не скажет иное |
reference_images_to_video | prompt плюс 1–7 reference_images (строки или объекты {"url":"..."}) | Одна запись reference_images без этого режима — устаревший одиночный ввод по-прежнему ведёт себя как first-frame |
Успешная котировка не гарантирует, что канал генерации открыт. Режимы доступны только после включения на совместимом канале; неподдерживаемые комбинации могут быть отклонены до создания задачи.
Типичные значения соотношения сторон в справочниках Grok Video: 16:9, 9:16, 3:2, 2:3 и 1:1. Доступность зависит от канала, поэтому отправляйте значение, подтверждённое для этого ID.

Рис. 1: Отправьте промпт (и при необходимости публичные URL изображений) на POST /v1/videos/generations, опрашивайте тот же id задачи и читайте result.data[0].url только после status completed.
Если нужны возможности официального канала Grok Imagine, например продление видео, это другое семейство ID — см. руководство по официальному каналу Imagine. Для второго видеоконтракта с другой матрицей длительности см. руководство по Hailuo 2.3.
3. Продакшен-реализация: cURL и Python
Международные примеры этой серии используют https://api.toapis.com. Официальная документация предписывает пользователям в материковом Китае https://toapis.cn. Оставляйте один origin на среду. Пути, ID моделей и заголовок Bearer остаются теми же.
Шаг 1: отправка grok-video-1.5 через 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-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" и URL в image. Задание с референсами задаёт "video_generation_mode": "reference_images_to_video" и список reference_images, оставляя resolution равным 480p или 720p.
Шаг 2: помощник на Python для отправки и опроса
Фрагмент следует документированному пути статуса и состояниям queued / in_progress / completed / failed. Перед выпуском сверьте id, result.data[0].url и конверт ответа со справочником API вашего аккаунта.
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 или таймаут клиента | Временный сбой шлюза или Upstream | Запросите существующий id задачи до повторной отправки |
status: queued или in_progress | Это не ошибка | Подождите и опросите снова; не создавайте вторую задачу |
status: failed | Генерация не удалась | Прочитайте error.code и error.message (и error.reason, если есть). Не повторяйте без изменений тело, отклонённое политикой |
5. Цены и FinOps ROI
- Не переиспользуйте удельные цены из черновиков планирования. Справочник API
grok-video-1.5указывает, что тарификация следует текущей конфигурации аккаунта и SKU и что страница не гарантирует фиксированную цену за секунду. Официальные справочные строки поставщика на странице цен ToAPIs носят ознакомительный характер и могут не совпадать с фактическим биллингом аккаунта. - Котировка не гарантирует канал. Справочник 1.5 отмечает, что успешная котировка не означает доступность канала генерации.
- Контролируйте расходы на уровне промпта: делайте черновики в
720pи средней длительности около 8 секунд, храните версионированный шаблон, меняйте по одной переменной и не переотправляйте после таймаута клиента, пока не проверите статус задачи. - Официальные контракты поставщиков часто добавляют годовые обязательства, квоты мест и предоплату. Биллинг ToAPIs обычно идёт по факту использования — подтвердите действующие условия в аккаунте.
6. Часто задаваемые вопросы
См. блок FAQ во frontmatter. Кратко: grok-video-3 не является текущим публичным ID каталога; начинайте с grok-video-1.5 или grok-video-1.0; потолок длительности 1.0 считайте канальной проверкой; синхронное аудио не документировано; всегда опрашивайте путь статуса generations и сохраняйте id задачи.
7. Чек-лист действий
- Создайте ключ на портале разработчика ToAPIs.
- Убедитесь, что
grok-video-1.5илиgrok-video-1.0видны вашему ключу черезGET /v1/models?type=video— не отправляйтеgrok-video-3, пока этот ID не появится и в списке, и в справочнике API. - Проведите дымовой тест cURL с
video_generation_mode: "text_to_video",duration: 8иresolution: "720p". - Опрашивайте
GET /v1/videos/generations/{id}с ограниченным дедлайном и скачайте результат доexpires_at. - Далее: руководство по OpenAI-совместимому доступу, если настраиваете существующий клиент; model-guide Grok Video 1.5 для живого статуса каталога; model-guide Grok Video 1.0 перед тем, как опираться на длительность больше 6 секунд на этом ID.







