Как вызвать Grok Video 3 API через OpenAI-совместимые эндпоинты
Целевые модели:
grok-video-1.5,grok-video-1.0
Эндпоинт инференса:https://api.toapis.com/v1/videos/generations
Связанные материалы: Практическое руководство по Grok Video · Официальный канал Grok Imagine · Настройка Chatbox · Список моделей
1. Краткое содержание и обзор (TL;DR)
- Что здесь значит «OpenAI-совместимость»: ToAPIs документирует единый origin
/v1, аутентификацию Bearer, а также список моделей и chat completions в стиле OpenAI. Публичные ID Grok Video зарегистрированы в семействе эндпоинтов каталогаopenai-video. Это не означает, что неопубликованныйgrok-video-3заработает, и не документирует само по себе метод OpenAI Videos SDK. - Идентификаторы: используйте
grok-video-1.5илиgrok-video-1.0после появления для вашего ключа вGET /v1/models?type=video. Снимок публичного каталога от 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. - Общая аутентификация: один API-ключ в
Authorization: Bearer. Отдельного публичного документа OAuth-scopes для этих видеовызовов нет. - Выбор клиента: OpenAI SDK с
base_url="https://api.toapis.com/v1"удобен для чата и привычной связки ключа и origin. Для Grok Video это руководство использует документированное REST JSON-тело, чтобы явно сохранитьvideo_generation_modeи поля URL изображений.
2. Совместимый origin, список моделей и видеопути
Держите origin, префикс /v1 и ключ вместе. Смешивать ключ ToAPIs с https://api.openai.com/v1 или origin 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 | Совместно используются только origin и ключ |
На grok-video-1.5 задайте video_generation_mode как text_to_video, first_frame_image_to_video или reference_images_to_video, чтобы JSON совпадал с отправляемыми медиа. Полевой контракт описан в практическом руководстве по Grok Video и в справочнике API Grok Video 1.5.

Рис. 1: Направьте клиент на origin 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. Оставляйте один origin на среду.
Шаг 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, проверьте точную строку id в списке моделей. Если grok-video-3 отсутствует, не отправляйте его.
Шаг 2: Python — общий origin и REST-вызовы видео
OpenAI SDK показан только для общего base_url и API-ключа. Создание и опрос видео остаются на документированных путях generations, чтобы поля тела 1.5 не потерялись в неофициальном сопоставлении клиента.
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 и согласуйте разбор со страницей Список моделей для вашего аккаунта. Не изобретайте запасной путь, который отправляет grok-video-3, когда ID отсутствует.
4. Обработка ошибок и матрица статусов
Категории ниже — отправная точка диагностики, а не гарантия точных кодов ошибок ToAPIs. Успешный HTTP-запрос всё равно требует чтения status задачи. См. справочник ошибок.
| HTTP или состояние задачи | Типичная категория | Рекомендуемое действие |
|---|---|---|
400 | Неизвестный ID модели, несоответствие режима и медиа или видеотело, отправленное на чат-путь | Подтвердите ID в GET /v1/models?type=video, что вы отправили POST на /v1/videos/generations, и что задания 1.5 содержат согласованный video_generation_mode |
401 | Отсутствует или недействителен API-ключ | Используйте ключ ToAPIs, а не ключ платформы OpenAI, и проверьте заголовок Bearer |
404 | Неверный origin, отсутствует /v1 или придуманный путь вроде /videos/tasks/{id} | Перейдите на GET /v1/videos/generations/{id} на том origin, которым вы отправляли задание |
429 | Ограничение частоты или параллелизма | Соблюдайте Retry-After, если он есть; делайте паузу с джиттером |
5xx или таймаут клиента | Временный сбой шлюза или Upstream | Запросите существующий 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. Часто задаваемые вопросы
См. блок FAQ во frontmatter. Кратко: совместимый origin не открывает grok-video-3; /v1 добавляйте один раз; опрашивайте /v1/videos/generations/{id}; не предполагайте помощник SDK videos.create; chat completions не вернут MP4.
7. Чек-лист действий
- Создайте ключ на портале разработчика ToAPIs.
- Направьте клиент на
https://api.toapis.com/v1(илиhttps://toapis.cn/v1в материковом Китае) с заголовкомAuthorization: Bearer. - Вызовите
GET /v1/models?type=videoи запишите точные ID Grok Video, видимые вашему ключу. - Проведите дымовой тест
POST /v1/videos/generationsсgrok-video-1.5иvideo_generation_mode: "text_to_video", затем опросите тот же id. - Далее: практическое руководство по Grok Video для режимов и полей изображений и model-guide Grok Video 1.5 для живого статуса каталога.







