> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Генерация видео Grok Imagine

> Полное руководство по официальному каналу видео xAI Grok Imagine на APIYI: grok-imagine-video / grok-imagine-video-1.5 / grok-imagine-video-1.5-lite, генерация text-to-video и image-to-video с нативным звуком, от 1 до 15 секунд, тарификация аналогична xAI — за секунду в зависимости от разрешения ($0.02–0.25/s). Совместимо с OpenAI Videos; доступ к группе GrokOfficial предоставляется по заявке.

## Обзор

**Grok Imagine Video** — это **официальный канал** для видеомоделей xAI: запросы перенаправляются через APIYI в официальный API xAI, **стоимость соответствует прайс-листу xAI**, а тарификация рассчитывается по количеству сгенерированных секунд и разрешению. API представляет собой совместимый с OpenAI Videos эндпоинт асинхронных задач (`/v1/videos`) с поддержкой режимов **text-to-video** и **image-to-video**, при этом каждое видео содержит звуковую дорожку.

Доступны три модели:

* **`grok-imagine-video`**: базовая модель, 480p / 720p
* **`grok-imagine-video-1.5`**: более новая модель, 480p / 720p / 1080p
* **`grok-imagine-video-1.5-lite`**: облегченная версия 1.5, самая низкая цена при 480p / 720p

> [!WARNING]
>
> **🔒 Для этого канала требуется группа `GrokOfficial`, доступ предоставляется по заявке**
>
> Grok Imagine Video не входит в группу `Default`. Политика безопасности контента этого семейства существенно отличается от других моделей на платформе, поэтому для снижения комплаенс-рисков доступ предоставляется **выборочно**:
>
> * **Действующие клиенты с суммарными расходами от \$1,000+**: свяжитесь с поддержкой, опишите ваш сценарий использования, и мы подключим доступ после проверки
> * **Все остальные пользователи**: подайте заявку через [поддержку в WeCom](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec), описав ваш **сценарий использования** и **механизмы модерации контента**; мы подключим доступ после одобрения
>
> Token без группы `GrokOfficial` возвращает **`503`** — это проблема с правами доступа, а не сбой сервиса. См. раздел [Настройка группы](#group-setup) ниже.

> [!WARNING]
>
> **⚠️ Без указания `size` по умолчанию используются 480p и 8 секунд**
>
> Если отправить запрос без указания разрешения или длительности, видео будет сгенерировано и тарифицировано как **480p, 8 секунд**. Чтобы получить разрешение 720p / 1080p или более короткий ролик, явно передайте `size` (например, `"1280x720"`) и `seconds`.

> **[API генерации видео](/ru/api-capabilities/grok-imagine-video/video-generation)**
>
> Отправка задач text-to-video / image-to-video с интерактивным Playground.

> **[Официальные изображения Grok Imagine](/ru/api-capabilities/grok-imagine-image-official/overview)**
>
> Та же группа `GrokOfficial` — генерация изображений по ценам xAI в зависимости от уровня.

## Интеграция с помощью ИИ-агента

Интегрируйте / проведите отладку генерации видео Grok Imagine (text-to-video + image-to-video) в этом проекте.

Перед написанием кода изучите документацию: загрузите [https://docs.apiyi.com/en/api-capabilities/grok-imagine-video/overview.md](https://docs.apiyi.com/en/api-capabilities/grok-imagine-video/overview.md), чтобы получить текстовую версию этой страницы; подробные сведения о параметрах можно получить, аналогично добавив `.md` к URL страницы генерации видео.

Требования:

1. Выберите одну модель: `grok-imagine-video` (480p / 720p), `grok-imagine-video-1.5` (480p / 720p / 1080p) или `grok-imagine-video-1.5-lite` (облегченная 1.5). Группа Token должна включать `GrokOfficial` с режимом тарификации Pay-as-you-go Priority или Pay-as-you-go, иначе каждый вызов будет возвращать 503.

2. Асинхронный трехэтапный процесс: `POST /v1/videos` для отправки и получения задачи `id` → опрос `GET /v1/videos/{id}` каждые 5–10 секунд, пока `status` не станет `completed` или `failed` → скачивание MP4 по `GET /v1/videos/{id}/content` (с тем же заголовком Authorization). Ограничьте общее время опроса 10 минутами.

3. Передавайте разрешение и длительность явно: `size` в пикселях (например, `"1280x720"`, `"720x1280"`, `"1920x1080"`); меньшая сторона определяет уровень (≥1080 — это 1080p, ≥720 — это 720p, иначе 480p), а соотношение сторон округляется до ближайшего поддерживаемого. `seconds` принимает значения от 1 до 15. **Без них по умолчанию используются 480p и 8 секунд, и именно за них взимается плата.** `grok-imagine-video` не поддерживает 1080p и возвращает 400 при таком запросе.

4. Image-to-video: добавьте `input_reference` на том же эндпоинте, указав публичный URL изображения или URI `data:image/...;base64,...`; либо загрузите файл через multipart с именем поля `input_reference`. Кадр на выходе следует за входным изображением.

5. Тарификация: сгенерированные секунды × посекундный тариф для разрешения, плюс небольшая комиссия за каждое входное изображение для image-to-video. Отключение звука не снижает стоимость.

6. Модерация: задача, заблокированная модерацией контента, по-прежнему имеет `status` `completed`, но видео отсутствует, в ответе возвращается `error.code: "moderation_blocked"`, **и она все равно тарифицируется**. Проверяйте это поле в коде — не считайте это успешным завершением и не повторяйте тот же prompt вслепую.

7. Видео можно скачать, как только задача перейдет в статус `completed`; сразу же сохраните его в собственное объектное хранилище вместо того, чтобы сохранять ссылку.

8. Считывайте ключ из переменной окружения `APIYI_API_KEY` и используйте [https://api.apiyi.com/v1](https://api.apiyi.com/v1) в качестве base\_url; никогда не зашивайте его в код и не фиксируйте в git. После завершения выполните один реальный запуск задачи text-to-video длительностью 2 секунды в 480p и покажите длительность клипа, разрешение и стоимость вызова.

## Модели и цены

Тарифы соответствуют официальным ценам xAI, а тарификация производится **за секунду сгенерированного видео**; ставка зависит от модели и разрешения:

| Модель | 480p | 720p | 1080p | Входное изображение image-to-video |
| - | - | - | - | - |
| **`grok-imagine-video`** | \$0.05 / с | \$0.07 / с | Не поддерживается | \$0.002 / изображение |
| **`grok-imagine-video-1.5`** | \$0.08 / с | \$0.14 / с | \$0.25 / с | \$0.01 / изображение |
| **`grok-imagine-video-1.5-lite`** | \$0.02 / с | \$0.03 / с | \$0.14 / с | \$0.01 / изображение |

> [!NOTE]
>
> Цены на модели синхронизированы с официальными сайтами и могут меняться вслед за ними; таблица выше приведена только для справки, а актуальные данные всегда указаны на вкладке **Цены на модели** в верхней навигации: [Цены на модели](/en/models/index).

> [!NOTE]
>
> **Примечания по тарификации и пример**
>
> * **Стоимость = секунды × тариф за секунду + входные изображения × плата за изображение**. Пример: задача image-to-video длительностью 1 секунда в разрешении 480p на `grok-imagine-video` = 1 × \$0.05 + 1 × \$0.002 = **\$0.052** (соответствует списанию в наших тестах).
> * **Значения по умолчанию также тарифицируются**: без параметров `size` / `seconds` задача запускается в 480p на 8 секунд — \$0.40 на `grok-imagine-video`.
> * **Аудио не тарифицируется отдельно**: видео по умолчанию содержат аудиодорожку, и её отключение не снижает цену.
> * **Блокировки модерации тарифицируются**: xAI взимает плату за видео, заблокированные её модерацией, и мы списываем средства на тех же условиях — см. [FAQ](#faq).
> * Дополнительно действуют [многоуровневые бонусы за пополнение](/ru/faq/recharge-promotions); корпоративные клиенты с крупными объёмами могут обратиться в отдел продаж для обсуждения индивидуальных тарифов.

## Настройка группы

> [!WARNING]
>
> **Grok Imagine Video не входит в группу `Default`.** Он находится в **группе `GrokOfficial` (та же цена, что и у xAI, то есть в таблице выше)** вместе с [официальными изображениями Grok Imagine](/ru/api-capabilities/grok-imagine-image-official/overview), и доступ к нему необходимо запрашивать.

### Кто может получить доступ

| Категория клиентов | Как получить доступ |
| - | - |
| **Действующие клиенты с совокупными расходами от \$1,000** | Обратитесь в службу поддержки с описанием вашего сценария использования; подключается после проверки |
| **Все остальные** | Подайте заявку с описанием вашего сценария использования и мер модерации контента; подключается после одобрения |

### Как подать заявку

**1. Обратитесь в службу поддержки WeCom**

Подайте заявку через [поддержку WeCom](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec) или напишите на [hi@apiyi.com](mailto:hi@apiyi.com). Укажите, что вы подаете заявку на **`GrokOfficial` (Grok Imagine Official)**.

**2. Опишите сценарий использования и меры модерации**

Осветите три момента: для чего создаются видео, кто является конечными пользователями и какие процедуры проверки контента и ручного контроля действуют на вашей стороне. Чем конкретнее информация, тем быстрее пройдет рассмотрение.

**3. Переключите группу Token после одобрения**

После одобрения мы включим `GrokOfficial` для вашего аккаунта. Перейдите на [страницу Token в консоли](https://api.apiyi.com/token), переключите Token, используемый для этого канала, на `GrokOfficial` и установите режим тарификации на `Pay-as-you-go Priority` или `Pay-as-you-go`.

> [!NOTE]
>
> **Как это выглядит до предоставления доступа**: Token без группы `GrokOfficial` возвращает **`503` (нет доступного канала в текущей группе)**. Повторные попытки не помогут — сначала необходимо подключить группу.
>
> **Не используйте режим тарификации `Pay-per-request`**: этот канал тарифицируется посекундно, поэтому Token с оплатой за запрос не сможет быть маршрутизирован и также вернет 503.

> [!NOTE]
>
> **Напоминание о соблюдении требований**: после предоставления доступа ответственность за сгенерированный контент несет вызывающая сторона. Соблюдайте местное законодательство и нормативные требования; запрещено генерировать незаконный контент, материалы, нарушающие права на изображение или интеллектуальную собственность третьих лиц, а также контент, не предназначенный для несовершеннолетних. При распространении среди конечных пользователей добавьте собственный уровень модерации. Подробнее: [Рекомендации по соблюдению требований при обращении к зарубежным моделям](/ru/faq/overseas-model-compliance). В случае выявления нарушений доступ к группе аннулируется.

## Технические характеристики

| Параметр | Характеристика |
| - | - |
| ID моделей | `grok-imagine-video`, `grok-imagine-video-1.5`, `grok-imagine-video-1.5-lite` |
| Возможности | Генерация видео по тексту, генерация видео по изображению (одно входное изображение) |
| Длительность | `seconds` 1–15, **по умолчанию 8** |
| Разрешение | 480p (по умолчанию) / 720p / 1080p (1080p недоступно для `grok-imagine-video`) |
| Соотношение сторон | `size` привязывается к ближайшему из `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3`; в режиме генерации видео по изображению соответствует входному изображению |
| Аудио | Включено по умолчанию |
| Время генерации | Около 20–25 с для 2 с при 480p; около 35–50 с для генерации видео по изображению; около 110 с для 1080p на 1.5 |
| Скачивание | Доступно по `/v1/videos/{id}/content`, как только задача получит статус `completed` |
| Рекомендуемая частота опроса | Каждые 5–10 секунд, с общим ограничением в 10 минут |

## Эндпоинты

| Шаг | Метод | Путь | Примечания |
| - | - | - | - |
| ① Отправка | `POST` | `/v1/videos` | `application/json`; для image-to-video также можно загрузить файл с помощью `multipart/form-data` |
| ② Проверка статуса | `GET` | `/v1/videos/{id}` | Возвращает `status` / `progress`, а также `seconds` после завершения |
| ③ Скачивание | `GET` | `/v1/videos/{id}/content` | Возвращает MP4; требуется заголовок Authorization |

> [!TIP]
>
> Основной домен `https://api.apiyi.com`, резервный домен `https://b.apiyi.com`. Полные примеры кода: [API генерации видео](/ru/api-capabilities/grok-imagine-video/video-generation).

### Сквозной процесс (Python)

```python theme={null}
import os, time, requests

BASE = "https://api.apiyi.com/v1"
H = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}

# ① Submit: 720p landscape, 5 seconds
task = requests.post(f"{BASE}/videos", headers=H, json={
    "model": "grok-imagine-video-1.5",
    "prompt": "a red paper boat drifting on a calm lake, gentle ripples, soft morning light",
    "seconds": "5",
    "size": "1280x720",
}, timeout=60).json()
vid = task["id"]

# ② Poll
for _ in range(60):
    time.sleep(8)
    job = requests.get(f"{BASE}/videos/{vid}", headers=H, timeout=60).json()
    if job["status"] in ("completed", "failed"):
        break

if job["status"] == "failed" or job.get("error"):
    # A moderation block also reports completed, but with error.code = moderation_blocked
    raise RuntimeError(job.get("error"))

# ③ Download the video and store it right away
mp4 = requests.get(f"{BASE}/videos/{vid}/content", headers=H, timeout=300)
open("out.mp4", "wb").write(mp4.content)
```

## Ключевые параметры

### `size` (разрешение и соотношение сторон)

`size` использует `WIDTHxHEIGHT` пикселей; шлюз выбирает уровень разрешения по **меньшей стороне** и сопоставляет **соотношение сторон** с ближайшим поддерживаемым:

| Пример `size` | Результат |
| - | - |
| `"854x480"` | 480p, 16:9 (фактический результат: 848×480) |
| `"1280x720"` | 720p, 16:9 (фактический результат: 1280×720) |
| `"720x1280"` | 720p, 9:16 (фактический результат: 720×1280) |
| `"1920x1080"` | 1080p, 16:9 (только 1.5 / 1.5-lite) |

Вы также можете передавать `"480p"` / `"720p"` / `"1080p"` напрямую или пропустить `size` и отправить нативные поля xAI `resolution` (`480p` / `720p` / `1080p`) плюс `aspect_ratio` (например, `9:16`); если присутствуют оба варианта, приоритет имеют `resolution` / `aspect_ratio`. Если не указан ни один, видео генерируется в разрешении **480p**.

> [!WARNING]
>
> `grok-imagine-video` поддерживает только 480p / 720p; значение `size` класса 1080p возвращает `400`: `grok-imagine-video resolution must be one of 480p, 720p`.

### `seconds` (продолжительность)

Целое число от **1 до 15**, в виде строки (`"5"`) или числа (`5`); **по умолчанию 8**. Значения вне диапазона возвращают `400`: `duration must be an integer between 1 and 15`. Стоимость зависит от количества секунд, поэтому при тестировании используйте 1–2 секунды.

### `input_reference` (генерация видео по изображению)

Передайте одно входное изображение, чтобы перевести задачу в режим генерации видео по изображению. Поддерживается любой из трех форматов:

* Публичный URL изображения: `"input_reference": "https://example.com/first-frame.jpg"`
* URI данных base64: `"input_reference": "data:image/jpeg;base64,/9j/4AAQ..."`
* Загрузка файла через multipart: `-F "input_reference=@first-frame.jpg"`

Для генерации видео по изображению используйте `prompt`, чтобы описать движение и камеру (например, «the cat slowly turns its head»); **выходной кадр следует за входным изображением**. Каждое входное изображение стоит дополнительно \$0.002 (`grok-imagine-video`) или \$0.01 (1.5 / 1.5-lite).

## Рекомендации

**1. Тестируйте prompt длительностью 1–2 секунды и с разрешением 480p**

Тарификация посекундная, поэтому проверяйте визуальный результат на коротких роликах низкого разрешения перед генерацией финальной версии в 720p / 1080p. У `grok-imagine-video-1.5-lite` самый низкий тариф для 480p / 720p, и эта модель отлично подходит для массовых экспериментов.

**2. Всегда передавайте size и seconds**

Если их не указать, по умолчанию применятся 480p и 8 секунд — самая частая причина вопросов «почему это так дорого» и «почему всё такое размытое».

**3. Опрашивайте статус каждые 5–10 секунд с общим таймаутом**

Задачи обычно завершаются за время от 20 секунд до 2 минут. Более частый опрос ничего не дает; ограничьте общее время ожидания 10 минутами и логируйте task ID для диагностики в случае таймаута.

**4. Обрабатывайте блокировки модерации**

Проверяйте `error.code` в ответе со статусом: `moderation_blocked` означает, что задача была заблокирована, видео не создано, а тарификация списана. Перед повторной отправкой перефразируйте prompt, а не повторяйте запрос в исходном виде.

**5. Сразу сохраняйте видео**

Скачивайте файл из `/content` сразу же, как только задача получит статус `completed`; не храните ссылку на скачивание долго и не передавайте её конечным пользователям.

## Коды ошибок и повторные попытки

| HTTP / поле | Значение | Что делать |
| - | - | - |
| `400` `invalid_request_error` | Недопустимые параметры: неподдерживаемое разрешение, `seconds` вне диапазона 1–15 и т. д.; подробности в `message` | Исправьте согласно указанию; не повторяйте запрос |
| `429` | Достигнут лимит запросов или недостаточно баланса | Повторите попытку с экспоненциальной задержкой и проверьте баланс |
| `503` | У token отсутствует группа `GrokOfficial` или используется тарификация с оплатой за запрос | **Проблема с правами доступа, а не сбой** — см. [Настройка групп](#group-setup) |
| `status: failed` | Сбой генерации | Ознакомьтесь с `error.message`, внесите изменения и отправьте повторно |
| `completed` + `error.code: moderation_blocked` | Заблокировано модерацией контента; видео не создано; тарифицируется | Измените prompt или исходное изображение перед повторной отправкой |

## FAQ

> **Каждый вызов возвращает 503 — канал недоступен?**
>
> Почти наверняка дело в правах доступа: у группы Token нет `GrokOfficial` либо для Token установлен режим тарификации с оплатой за запрос. В первом случае подайте заявку через [Настройка групп](#group-setup); во втором — переключите режим тарификации на `Pay-as-you-go Priority` или `Pay-as-you-go`.

> **Почему моё видео в разрешении 480p и длится 8 секунд?**
>
> Это параметры по умолчанию: без `size` и `seconds` задача генерируется и тарифицируется в качестве 480p длительностью 8 секунд. Передавайте `size` (например, `"1280x720"`) и `seconds` явно.

> **Задача сообщает completed, но видео для скачивания отсутствует?**
>
> Проверьте ответ со статусом на наличие `error.code: "moderation_blocked"`. Если он присутствует, модерация контента xAI заблокировала видео: задача по-прежнему возвращает `completed`, но самого видео нет, **и за него списывается плата** (xAI взимает оплату и за заблокированные видео). Скорректируйте prompt или исходное изображение и отправьте запрос повторно.

> **Без звука получается дешевле?**
>
> Нет. По умолчанию видео содержат аудиодорожку, и согласно тарифам xAI отключение звука не снижает стоимость.

> **Почему итоговый размер при генерации image-to-video не совпадает с отправленным?**
>
> Генерация image-to-video наследует пропорции кадра исходного изображения. Если требуется определённое соотношение сторон, обрежьте входное изображение до нужных пропорций перед отправкой.

> **Поддерживаются ли редактирование видео, продление или несколько референсных изображений?**
>
> В настоящее время этот канал поддерживает **text-to-video** и **image-to-video с одним входным изображением**. Редактирование видео, продление и подобные возможности пока недоступны; эта страница будет обновлена, когда они появятся.

> **Какую из трёх моделей выбрать?**
>
> * Требуется 1080p → `grok-imagine-video-1.5` (лучшее качество) или `grok-imagine-video-1.5-lite` (дешевле)
> * Пакетная генерация 480p / 720p при ограниченном бюджете → `grok-imagine-video-1.5-lite` (\$0.02 / \$0.03 за секунду)
> * Уже используете базовую модель и нужно только 480p / 720p → `grok-imagine-video`

## Связанная документация

* [API генерации видео Grok Imagine](/ru/api-capabilities/grok-imagine-video/video-generation) - справочник по эндпоинту отправки с Playground
* [Официальные изображения Grok Imagine](/ru/api-capabilities/grok-imagine-image-official/overview) - та же группа, цена по уровням аналогична xAI
* [Руководство по моделям Grok](/ru/api-capabilities/grok/overview) - текстовые модели xAI
* [Бонусы за пополнение](/ru/faq/recharge-promotions)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.