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

# Генерация видео MiniMax H3 с помощью Flatkey

> Создавайте задачи на генерацию видео MiniMax H3 из текста или референсных медиафайлов, отслеживайте их статус и скачивайте готовый MP4 через Flatkey.

Базовый URL: `https://router.flatkey.ai`

Используйте `MiniMax-H3`, когда вам нужна генерация видео из текста, управление первым и последним кадром, а также референсные изображения, видео и аудио. Каждый запрос следует одному и тому же асинхронному процессу: создать задачу, отслеживать её статус, затем скачать готовый MP4.

<CardGroup cols={2}>
  <Card title="Гибкие входные данные" icon="images">
    Генерируйте из текста, изображений кадров или референсных изображений, видео и аудио.
  </Card>

  <Card title="Единый асинхронный процесс" icon="video">
    Создавайте через `POST /v1/videos`, отслеживайте через `GET /v1/videos/{task_id}` и скачивайте из `metadata.url`.
  </Card>
</CardGroup>

Используйте этот заголовок для создания задач и запросов статуса:

```http theme={"dark"}
Authorization: Bearer YOUR_FLATKEY_API_KEY
```

Храните ваш API-ключ в тайне. Не вставляйте его в публичные логи, страницы или тикеты поддержки.

## Создайте своё первое видео H3

### 1. Отправьте задачу на генерацию видео из текста

Отправьте `POST /v1/videos` с моделью `MiniMax-H3` и текстовым промптом. Запросы, содержащие только текст, требуют явного указания соотношения сторон, отличного от `adaptive`.

<CodeGroup>
  ```bash Bash theme={"dark"}
  curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
    -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "MiniMax-H3",
      "content": [
        {
          "type": "text",
          "text": "A paper boat crosses a rain puddle in a cinematic macro shot"
        }
      ],
      "resolution": "768P",
      "duration": 6,
      "ratio": "16:9",
      "aigc_watermark": false
    }'
  ```

  ```powershell Windows PowerShell theme={"dark"}
  curl.exe --fail-with-body -sS https://router.flatkey.ai/v1/videos `
    -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" `
    -H "Content-Type: application/json" `
    -d '{
      "model": "MiniMax-H3",
      "content": [
        {
          "type": "text",
          "text": "A paper boat crosses a rain puddle in a cinematic macro shot"
        }
      ],
      "resolution": "768P",
      "duration": 6,
      "ratio": "16:9",
      "aigc_watermark": false
    }'
  ```
</CodeGroup>

Ответ содержит публичный идентификатор задачи в полях `id` и `task_id`:

```json theme={"dark"}
{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0
}
```

Сохраните возвращённое значение `task_...`. Оно понадобится вам для проверки статуса задачи.

### 2. Отслеживайте статус и скачайте результат

Опрашивайте `GET /v1/videos/{task_id}`, пока `status` не станет `completed` или `failed`. Когда статус `completed`, считайте временный URL для скачивания из `metadata.url`.

<CodeGroup>
  ```bash Bash theme={"dark"}
  TASK_ID="task_3f9a00000000000000000000000000e2"

  curl --fail-with-body -sS \
    "https://router.flatkey.ai/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer YOUR_FLATKEY_API_KEY"

  # Run the status request again until status is completed.
  # Then copy metadata.url from the response and paste it below.
  VIDEO_URL="PASTE_METADATA_URL_HERE"
  curl --fail --location "$VIDEO_URL" --output minimax-h3.mp4
  ```

  ```powershell Windows PowerShell theme={"dark"}
  $taskId = "task_3f9a00000000000000000000000000e2"

  while ($true) {
    $result = curl.exe --fail-with-body -sS `
      "https://router.flatkey.ai/v1/videos/$taskId" `
      -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" | ConvertFrom-Json
    Write-Host "status: $($result.status)"

    if ($result.status -eq "completed") { break }
    if ($result.status -eq "failed") {
      $result | ConvertTo-Json -Depth 10
      exit 1
    }
    Start-Sleep -Seconds 5
  }

  curl.exe --fail --location $result.metadata.url --output minimax-h3.mp4
  ```
</CodeGroup>

`metadata.url` — это временный URL для скачивания. Он работает без заголовка авторизации Flatkey, поэтому любой, кто его получит, сможет получить доступ к сгенерированному видео до его истечения. Относитесь к нему как к конфиденциальному: не логируйте, не публикуйте и не передавайте его. Скачайте видео незамедлительно и сохраните в своём хранилище. Повторный запрос статуса задачи не обновляет истёкший URL.

## Выберите входные данные

Каждый запрос должен содержать непустой текстовый элемент. Вы можете добавить изображения кадров или референсные медиафайлы для управления результатом.

| Входные данные          | `type`      | Обязательная `role`        | Ограничение                                                    |
| ----------------------- | ----------- | -------------------------- | -------------------------------------------------------------- |
| Промпт                  | `text`      | Не указывайте роль         | 7 000 символов Unicode суммарно по всем текстовым элементам    |
| Первый кадр             | `image_url` | `first_frame` или без роли | 1 изображение                                                  |
| Последний кадр          | `image_url` | `last_frame`               | 1 изображение                                                  |
| Референсное изображение | `image_url` | `reference_image`          | 9 изображений                                                  |
| Референсное видео       | `video_url` | `reference_video`          | 3 видео                                                        |
| Референсное аудио       | `audio_url` | `reference_audio`          | 3 аудиофайла; также включите референсное изображение или видео |

<Warning>
  Не смешивайте входные данные первого/последнего кадра с референсными входными данными в одном запросе. Каждый элемент `content` должен содержать ровно одну полезную нагрузку, соответствующую его `type`.
</Warning>

### Управляйте первым и последним кадром

Используйте `first_frame` и `last_frame`, когда хотите, чтобы видео интерполировало между двумя изображениями.

```bash theme={"dark"}
curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "The camera slowly pulls back as morning fog crosses the valley"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/first.jpg" },
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/last.jpg" },
        "role": "last_frame"
      }
    ],
    "resolution": "2K",
    "duration": 8,
    "ratio": "adaptive"
  }'
```

### Генерируйте с референсными медиафайлами

Референсные входные данные помогают сохранить субъект, стиль движения или звук. Референсное аудио не может быть единственным медиавходом.

```bash theme={"dark"}
curl --fail-with-body -sS https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "Keep the character and movement style consistent while crossing a snowy street"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/character.jpg" },
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/motion.mp4" },
        "role": "reference_video"
      },
      {
        "type": "audio_url",
        "audio_url": { "url": "https://example.com/ambience.mp3" },
        "role": "reference_audio"
      }
    ],
    "resolution": "768P",
    "duration": 10,
    "ratio": "adaptive"
  }'
```

## Настройки запроса

| Поле             | Обязательное                  | Поддерживаемые значения                                                            |
| ---------------- | ----------------------------- | ---------------------------------------------------------------------------------- |
| `model`          | Да                            | `MiniMax-H3`                                                                       |
| `content`        | Да                            | Текст плюс необязательные кадровые или референсные медиафайлы                      |
| `resolution`     | Да                            | `768P` или `2K`; значения чувствительны к регистру                                 |
| `duration`       | Да                            | Целое число от `4` до `15` секунд                                                  |
| `ratio`          | Для запросов только с текстом | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` или `adaptive` при наличии медиафайлов |
| `aigc_watermark` | Нет                           | `true` или `false`                                                                 |

Когда запрос содержит медиафайлы и не указывает `ratio`, Flatkey использует `adaptive`. Запрос только с текстом должен явно указывать соотношение сторон, отличное от `adaptive`.

## Понимание результатов задачи

| `status`      | Значение                                                         |
| ------------- | ---------------------------------------------------------------- |
| `queued`      | Задача ожидает выполнения.                                       |
| `in_progress` | Видео генерируется. Читайте `progress` для значения от 0 до 100. |
| `completed`   | Видео готово по адресу `metadata.url`.                           |
| `failed`      | Генерация не удалась. Читайте `error.code` и `error.message`.    |

Для ответов на видеозапросы H3 общие названия полей использования представляют секунды:

* `usage.completion_tokens` — продолжительность сгенерированного результата.
* `usage.total_tokens` — общая оплачиваемая продолжительность, включая время входного референсного видео.

Эти значения представляют секунды, а не токены языковой модели. Проверьте **Журналы использования** в [Консоли Flatkey](https://console.flatkey.ai/usage-logs/common) для получения итоговой суммы списания.

## Текущие ограничения

* `callback_url` не поддерживается. Вместо этого опрашивайте статус задачи.
* Листинг задач, отмена, удаление, повторная генерация и ремикс не поддерживаются.
* `MiniMax-H3-Context-IR` не поддерживается.
* Удалённые URL медиафайлов должны оставаться доступными в течение всего времени обработки задачи.

| Код ошибки                 | Что проверить                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `invalid_duration`         | Установите `duration` от `4` до `15`.                                                                                      |
| `invalid_resolution`       | Используйте точно `768P` или `2K`.                                                                                         |
| `invalid_ratio`            | Используйте поддерживаемое соотношение сторон. Запросы только с текстом не могут его опускать или использовать `adaptive`. |
| `invalid_content`          | Проверьте промпт, роли, ограничения на медиафайлы и несовместимые комбинации входных данных.                               |
| `unsupported_callback_url` | Удалите `callback_url` и опрашивайте статус задачи.                                                                        |