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

# Видеомодели Grok Imagine

> Две видеомодели xAI в WideRouter: генерация, редактирование и расширение клипов, а также настройка длительности, разрешения, референсных изображений и предустановленных голосов.

Две модели семейства Grok Imagine создают видео. Обе работают через
[асинхронный API задач](/ru/api/async-tasks) с той же оболочкой, что и всё остальное —
синхронного эндпоинта для видео нет, поэтому это единственный способ обратиться к ним.

Это не просто пара «старой» и «новой» моделей. `grok-imagine-video-1.5` генерирует видео
в более высоком разрешении и может использовать предустановленные голоса; `grok-imagine-video` —
единственная модель, которая принимает **видео в качестве входных данных**, что необходимо
для редактирования и расширения видео. Выбор зависит от того, создаёте ли вы клип или изменяете его.

## Серия: краткий обзор

|                                        | Grok Imagine Video 1.5        | Grok Imagine Video   |
| -------------------------------------- | ----------------------------- | -------------------- |
| **Идентификатор модели**               | `grok-imagine-video-1.5`      | `grok-imagine-video` |
| Текст в видео                          | да                            | да                   |
| Изображение в видео (первый кадр)      | да                            | да                   |
| Референсные изображения                | да, до 3                      | да, до 3             |
| **Редактирование существующего клипа** | нет                           | **да**               |
| **Продление существующего клипа**      | нет                           | **да**               |
| Разрешения                             | `480p` / `720p` / **`1080p`** | `480p` / `720p`      |
| Предустановленные голоса               | **да**, до 3                  | нет                  |
| Выход без звука                        | да                            | да                   |
| Длительность                           | 1–15 с                        | 1–15 с               |

Запрос функции, которую модель не поддерживает, завершается ошибкой при отправке — до постановки в очередь. В сообщении указывается, какую модель следует использовать вместо неё:

```json theme={null}
{
  "error": {
    "code": "invalid_params",
    "message": "edit needs a model that takes video input; use grok-imagine-video",
    "param": "input.mode"
  }
}
```

## Режимы

`input.mode` выбирает действие модели. Он принимает `generate`, `edit` или
`extend`, а по умолчанию используется `generate`.

| `mode`     | Требует `input.video` | Длительность результата  | Модели                      |
| ---------- | --------------------- | ------------------------ | --------------------------- |
| `generate` | нет                   | `duration`, плюс 0,04 с  | обе                         |
| `edit`     | да                    | **наследует исходник**   | только `grok-imagine-video` |
| `extend`   | да                    | исходник плюс `duration` | только `grok-imagine-video` |

`edit` переписывает существующий клип по prompt и сохраняет его длительность, поэтому не
принимает `resolution` — результат соответствует исходнику. `extend` добавляет новые
кадры в конец.

```json theme={null}
{
  "model": "grok-imagine-video",
  "input": {
    "prompt": "the camera slowly pulls back",
    "mode": "extend",
    "video": "https://example.com/boat.mp4",
    "duration": 3
  }
}
```

Измерено: исходник длительностью 3,04 секунды с `duration: 3` создал **6,04-секундный**
клип — исходник плюс трёхсекундное расширение, а не повторный рендеринг.

<Warning>
  **Диапазон `duration` сужается в режиме `extend`.** Контракт допускает 1–15
  секунд, но расширение фактически ограничено **2–10 секундами**, а сам
  исходный клип должен иметь длительность **не менее 2 секунд**. Ни одно из ограничений
  не проверяется при отправке, поэтому оба возвращаются как ошибка на уровне задачи после постановки
  задачи в очередь:

  `Duration must be between 2 and 10 seconds` · `Input video must be at least 2 seconds long, got 1.0s`
</Warning>

## Параметры

Все перечисленное ниже помещается внутрь `input`. Конверт описан в
[API асинхронных задач](/ru/api/async-tasks).

| Поле               | Тип       | По умолчанию                 | Примечания                                                                                      |
| ------------------ | --------- | ---------------------------- | ----------------------------------------------------------------------------------------------- |
| `prompt`           | string    | —                            | Обязательное поле.                                                                              |
| `mode`             | string    | `generate`                   | `generate`, `edit` или `extend`.                                                                |
| `duration`         | integer   | значение модели по умолчанию | 1–15 секунд. Предупреждение для `extend` приведено выше.                                        |
| `resolution`       | string    | `480p`                       | `480p`, `720p` или `1080p` только для 1.5. Не принимается в режиме `edit`.                      |
| `aspect_ratio`     | string    | `16:9`                       | Одно из значений: `1:1` `16:9` `9:16` `4:3` `3:4` `3:2` `2:3`.                                  |
| `images`           | string\[] | —                            | Ровно одно изображение, используемое как **первый кадр**.                                       |
| `video`            | string    | —                            | Исходный клип для `edit` и `extend`. `https` URL или URI данных видео в формате base64.         |
| `reference_images` | string\[] | —                            | До 3 изображений, из которых модель заимствует стиль и объект. Нельзя комбинировать с `images`. |
| `voice_ids`        | string\[] | —                            | До 3 предустановленных голосов. Только `grok-imagine-video-1.5`.                                |
| `generate_audio`   | boolean   | `true`                       | Установите `false` для клипа без звука. Цена не изменяется.                                     |

Параметра `n` не существует — видеомодели создают один клип на задачу.

<Note>
  В отличие от моделей для изображений, для видео нет **соотношения сторон `auto`** и сверхшироких
  соотношений сторон. Семь приведенных выше значений составляют полный список.
</Note>

## Разрешение и длительность

Измеряемые выходные пиксели, по одному примеру для каждого уровня:

| `resolution` | `aspect_ratio`        | Результат   |
| ------------ | --------------------- | ----------- |
| `480p`       | `16:9` (по умолчанию) | 848 × 480   |
| `480p`       | `9:16`                | 480 × 848   |
| `720p`       | `16:9`                | 1280 × 720  |
| `1080p`      | `16:9`                | 1920 × 1088 |

`1080p` отклоняется на `grok-imagine-video` с сообщением
`1080p is only available on grok-imagine-video-1.5`.

**Длительность клипов примерно на 0,04 секунды больше запрошенной** — запросите 3 секунды,
и файл будет длительностью 3,04 секунды. Это неизменно для каждого примера и не
влияет на тарификацию: она рассчитывается исходя из запрошенной длительности.

## Эталонные изображения, первые кадры и голоса

Можно передать три разных типа данных, причём два из них взаимоисключающие:

* **`images`** — это **первый кадр**. Ровно одно изображение, и клип анимируется, начиная с него.
* **`reference_images`** задаёт стиль и объект, допускается до трёх изображений. Обе модели принимают этот параметр, но его использование **ограничивает результат значением `720p`** — сочетание `reference_images` с `1080p` отклоняется с ошибкой
  `reference images are capped at 720p`.
* Передача обоих параметров отклоняется:
  `cannot be combined with images; a first frame and reference images are different modes`.

`voice_ids` выбирает предустановленные голоса в `grok-imagine-video-1.5` — до трёх на клип. Допустимые значения:

|          |           |          |          |          |          |
| -------- | --------- | -------- | -------- | -------- | -------- |
| `ara`    | `eve`     | `leo`    | `rex`    | `sal`    | `carina` |
| `zagan`  | `helix`   | `orion`  | `luna`   | `iris`   | `altair` |
| `zenith` | `perseus` | `helios` | `lux`    | `kepler` | `rigel`  |
| `cosmo`  | `celeste` | `ursa`   | `sirius` | `lumen`  | `castor` |
| `naksh`  | `atlas`   |          |          |          |          |

Пользовательские голоса недоступны в WideRouter. Обратите внимание: сам идентификатор голоса **не проверяется во время отправки** — неизвестное имя принимается, после чего задача завершается с ошибкой. Ни голоса, ни `generate_audio: false` не изменяют стоимость.

## Тарификация

Эти модели обслуживаются через группу **`Grok-Official`**. Прайсовая
цена WideRouter в точности соответствует официальной цене xAI — скидка действует через **коэффициент тарифа**
группы, который составляет `0.8` для `Grok-Official`. Таким образом, вы платите:

```
list price × group multiplier = charge
```

Стоимость видео рассчитывается **за секунду результата** в зависимости от разрешения. Вот прайсовые цены:

| Модель                   | `480p`     | `720p`     | `1080p`    |
| ------------------------ | ---------- | ---------- | ---------- |
| `grok-imagine-video-1.5` | \$0.08 / с | \$0.14 / с | \$0.25 / с |
| `grok-imagine-video`     | \$0.05 / с | \$0.07 / с | недоступно |

Три правила, которые не отражает одна лишь посекундная ставка:

* **Отправленные вами медиафайлы также тарифицируются.** Эталонное изображение добавляет примерно \$0.01;
  исходный клип для `edit` или `extend` тарифицируется за секунду собственной длительности —
  около \$0.01 за секунду.
* **`extend` не тарифицирует исходный материал повторно.** По посекундной ставке оплачивается только
  новый сегмент, плюс исходный клип как входные данные. Измерено: продление
  3.04-секундного клипа на 3 секунды стоило \$0.18 — три секунды результата по \$0.05 плюс
  3.04 секунды входных данных по \$0.01 — при итоговой длительности 6.04 секунды.
  Повторная генерация шести секунд с нуля обошлась бы в \$0.30.
* **`edit` стоит примерно вдвое больше длительности исходника**, один раз как результат и один раз как
  входные данные. Измерено: редактирование 1.04-секундного клипа стоило \$0.06.

Полный пример от начала до конца. Три секунды `480p` на `grok-imagine-video`:

```
\$0.05 / s × 3 s        = \$0.15   list price
\$0.15 × 0.8            = \$0.12   charged on Grok-Official
```

<Info>
  У выполненной задачи указано `usage.cost_in_usd_ticks`, где `10000000000`
  единиц соответствует \$1. Это значение является **прайсовой ценой** — до применения коэффициента вашей группы.
  Умножьте его на ставку вашей группы, чтобы узнать сумму, которая фактически списывается с вашего баланса.
</Info>

## Задержка

Измерено от начала до конца в асинхронном API, от отправки до `completed`:

| Запрос                                               | От начала до конца |
| ---------------------------------------------------- | ------------------ |
| `grok-imagine-video`, `480p`, 1 s                    | 19 s               |
| `grok-imagine-video-1.5`, `480p`, 1 s                | 21 s               |
| `grok-imagine-video`, `480p`, 3 s                    | 21–30 s            |
| `grok-imagine-video`, `edit` клипа длительностью 1 s | 30 s               |
| `grok-imagine-video`, `extend` за 3 s                | 30 s               |
| `grok-imagine-video-1.5`, `1080p`, 3 s               | \~48 s             |
| `grok-imagine-video-1.5`, `480p`, 15 s               | \~51 s             |

Генерация происходит значительно быстрее, чем «обычно несколько минут», которые часто указывают для моделей генерации видео, но всё же занимает достаточно много времени, чтобы удерживать соединение открытым было нельзя — поэтому синхронного эндпоинта нет. Выполняйте опрос каждые две–три секунды и задавайте тайм-аут клиента исходя из самой медленной строки в этой таблице, а не из самой быстрой.

## Если задача завершается с ошибкой

Ошибки видео возвращаются как задача `failed` с объектом `error`, а не как ошибка HTTP — эндпоинт чтения по-прежнему возвращает `200`. Распространённый код — `upstream_error`, а сообщение передаётся напрямую от xAI:

```json theme={null}
{
  "status": "failed",
  "counts": { "requested": 1, "succeeded": 0, "failed": 1 },
  "error": {
    "code": "upstream_error",
    "message": "Input video must be at least 2 seconds long, got 1.0s"
  }
}
```

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

## Следующие шаги

<CardGroup cols={2}>
  <Card title="Среда тестирования" icon="play" href="/ru/models/grok-imagine/video/playground">
    Отправьте реальную задачу на генерацию видео из браузера и отслеживайте её выполнение до завершения.
  </Card>

  <Card title="Изображение Grok Imagine" icon="image" href="/ru/models/grok-imagine/image/overview">
    Графическая часть семейства — три варианта и сетка качества.
  </Card>
</CardGroup>