Grok Imagine 1.0 Video Generation 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)
- Идентификаторы: запросы под заголовком «Grok Imagine 1.0» должны использовать строки, которые ToAPIs действительно публикует. Снимок публичного каталога от 2026-11-10 перечисляет
grok-imagine-video-officialиgrok-imagine-video-1.5-official(оба также появляются в image-generation и вopenai-video). Проверка пути документацииgrok-imagine-1.02026-11-17 вернула HTTP 404. - Аутентификация: отправляйте
Authorization: Bearer $TOAPIS_API_KEY. Официальные страницы не документируют OAuth-scopes, гранулярные имена прав или эндпоинт обнаружения scopes для этих вызовов. - Эндпоинты: создание —
POST /v1/videos/generations. Опрос —GET /v1/videos/generations/{id}. Продление вывода официального канала —POST /v1/videos/{video_id}/extendлибоPOST /v1/videos/extendсvideo_urls, если есть только публичный URL видео. Загрузка кадров —POST /v1/uploads/images. - Возможности:
grok-imagine-video-officialзакрывает text-to-video, image-to-video и несколько референсов при480pили720p, длительности 1–15 секунд и продлении на 2–10 секунд.grok-imagine-video-1.5-official— только image-to-video с первого кадра, требует ровно одноimage, допускает1080pи не поддерживает продление. - Форма тарификации (фиксированной публичной цены на страницах справочника нет): выход — посекундно по уровню разрешения; каждое входное изображение — за штуку; продление также тарифицирует длительность исходного видео. Подтверждайте живые тарифы аккаунта.
2. Эндпоинты, аутентификация и контракты моделей
Официальные документы используют https://toapis.com (и https://toapis.cn для материкового Китая). Другие руководства этой серии используют https://api.toapis.com. Выберите один origin и придерживайтесь его. Все пути ниже используют один и тот же заголовок Bearer.
| Действие | Метод и путь | Заметки по модели |
|---|---|---|
| Загрузка кадра | POST /v1/uploads/images | Multipart file. JPEG, PNG, WebP или GIF, максимум 30 МБ. Читайте data.url |
| Создание видео | POST /v1/videos/generations | Оба официальных ID Imagine |
| Запрос статуса | GET /v1/videos/generations/{id} | Один путь для задач генерации и продления |
| Продление из предыдущей задачи | POST /v1/videos/{video_id}/extend | Только grok-imagine-video-official. video_id — id предыдущей задачи генерации |
| Продление из публичного URL | POST /v1/videos/extend | Тот же официальный ID; video_urls обязателен, если в пути нет id |
| ID каталога | Документированные задачи | Длительность | Разрешение | Изображения | Продление |
|---|---|---|---|---|---|
grok-imagine-video-official | Text-to-video, первый кадр и несколько референсов | 1–15 секунд (по умолчанию 8) | 480p, 720p | Необязательные image и reference_images; всего до 7 | 2–10 секунд (duration по умолчанию 6) |
grok-imagine-video-1.5-official | Только image-to-video с первого кадра | 1–15 секунд (по умолчанию 8) | 480p, 720p, 1080p | image обязателен (ровно один первый кадр). Дополнительные reference_images тоже входят в лимит 7 | Не поддерживается |
Значения соотношения сторон в официальных справочниках Imagine включают 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 и 1:1. Отправляйте значение, подтверждённое для этого ID и канала.
Публичной строки scope, которой отдельно запрашивают «генерацию», «продление» или «загрузку», нет. Доступ определяется тем, что уже разрешают API-ключ, группа пользователей и конфигурация канала. Если вызов завершился ошибкой прав или доступности, проверяйте список моделей ключа и справочник ошибок, а не добавляйте выдуманный параметр scope.

Рис. 1: Один API-ключ Bearer уполномочивает загрузку, генерацию или продление и опрос статуса; официальный ID 1.5 не добавляет ветку продления.
Неофициальное семейство Grok Video (grok-video-1.0 / grok-video-1.5) описано в практическом руководстве по Grok Video. Эти ID — другой контракт и не наследуют этот путь продления.
3. Продакшен-реализация: cURL и Python
Шаг 1: cURL — text-to-video официального канала
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"])
Чтобы продлить публичный MP4, а не задачу по id, отправьте на POST /v1/videos/extend ту же официальную модель, промпт, duration и список video_urls. Не вызывайте продление с grok-imagine-video-1.5-official.
4. Обработка ошибок и матрица статусов
Категории ниже — отправная точка диагностики, а не гарантия точных кодов ошибок ToAPIs. Успешный HTTP-запрос всё равно требует чтения status задачи. Справочник ошибок различает ошибки запроса, значения error.reason у неуспешных задач и полезную нагрузку webhook.
| HTTP или состояние задачи | Типичная категория | Рекомендуемое действие |
|---|---|---|
400 | Недопустимое поле, отсутствует обязательный image на 1.5-official, превышен лимит изображений или продление отправлено модели, которая его не поддерживает | Проверьте точный официальный ID, длительность (1–15 при генерации, 2–10 при продлении), разрешение (1080p только на 1.5-official) и что все медиа — публичные URL |
401 | Отсутствует или недействителен API-ключ | Обновите ключ и проверьте Authorization: Bearer. Не добавляйте недокументированный параметр scope как обходной путь |
429 | Ограничение частоты или параллелизма | Соблюдайте Retry-After, если он есть; делайте паузу с джиттером |
5xx или таймаут клиента | Временный сбой шлюза или Upstream | Запросите существующий 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 | Таймаут или доступность Upstream | Сначала проверьте существующий id; повторяйте с паузой только если задача уже конечная |
5. Цены и FinOps ROI
Страницы официальной генерации и продления Imagine описывают форму тарификации, а не фиксированную публичную удельную цену:
Используйте тарифы, возвращённые для вашего аккаунта и SKU, а не числа из черновиков.
grok-imagine-video-1.5-officialвсегда включает одну плату за входное изображение, потому что первый кадр обязателен.- Продление — не бесплатное продолжение. Официальный биллинг продления включает сгенерированные секунды продления и длительность исходного видео. Цепочка продлений поэтому снова тарифицирует растущую длину источника — подтвердите это поведение живой котировкой, прежде чем строить цикл.
- Не переиспользуйте удельные цены и цифры SLA из черновиков планирования. Официальные справочные строки поставщика на странице цен ToAPIs носят ознакомительный характер и могут не совпадать с биллингом аккаунта.
- Делайте черновики в
720pи средней длительности, меняйте по одной переменной и не переотправляйте после таймаута клиента, пока не проверите статус задачи.
6. Часто задаваемые вопросы
См. блок FAQ во frontmatter. Кратко: отправляйте grok-imagine-video-official или grok-imagine-video-1.5-official, а не grok-imagine-1.0; аутентификация — API-ключ Bearer без публичной матрицы OAuth-scopes; 1.5-official — только first-frame и без продления; длительность продления 2–10 секунд и тарифицирует длину источника; всегда различайте HTTP-ошибки и status: failed.
7. Чек-лист действий
- Создайте ключ на портале разработчика ToAPIs.
- Убедитесь, что
grok-imagine-video-officialилиgrok-imagine-video-1.5-officialвидны вашему ключу черезGET /v1/models?type=video. - Проведите дымовой тест генерации официального канала в
720p, опроситеGET /v1/videos/generations/{id}и скачайте файл доexpires_at. - Если нужно продолжение, продлевайте только с
grok-imagine-video-officialиduration2–10 секунд, затем подтвердите, что котировка включает тарификацию длительности источника. - Далее: официальный model-guide Imagine и официальный model-guide Imagine 1.5 для живого статуса каталога и практическое руководство по Grok Video, если имелось в виду неофициальное семейство
grok-video-*.







