> ## 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.

# Generate MiniMax H3 videos with Flatkey

> Create MiniMax H3 video tasks from text or reference media, poll their status, and download the finished MP4 through Flatkey.

Base URL: `https://router.flatkey.ai`

Use `MiniMax-H3` when you need text-to-video, first- and last-frame control, or image, video, and audio references. Every request follows the same asynchronous workflow: create a task, poll its status, then download the finished MP4.

<CardGroup cols={2}>
  <Card title="Flexible inputs" icon="images">
    Generate from text, frame images, or reference images, videos, and audio.
  </Card>

  <Card title="One async workflow" icon="video">
    Create with `POST /v1/videos`, poll with `GET /v1/videos/{task_id}`, and download from `metadata.url`.
  </Card>
</CardGroup>

Use this header for task creation and status requests:

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

Keep your API key private. Do not paste it into public logs, pages, or support tickets.

## Create your first H3 video

### 1. Submit a text-to-video task

Send `POST /v1/videos` with the `MiniMax-H3` model and a text prompt. Text-only requests require an explicit aspect ratio other than `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>

The response contains the public task ID in both `id` and `task_id`:

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

Save the returned `task_...` value. You need it to check the task later.

### 2. Poll and download the result

Poll `GET /v1/videos/{task_id}` until `status` becomes `completed` or `failed`. When it is `completed`, read the temporary download URL from `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` is a temporary download URL. It works without a Flatkey authorization header, so anyone who has it can access the generated video until it expires. Treat it as private, and do not log, publish, or share it. Download the video promptly and store it in your own storage. Repeating the task query does not refresh an expired URL.

## Choose your inputs

Every request must contain a non-empty text item. You can add frame images or reference media to control the result.

| Input           | `type`      | Required `role`                 | Limit                                                  |
| --------------- | ----------- | ------------------------------- | ------------------------------------------------------ |
| Prompt          | `text`      | Do not set a role               | 7,000 Unicode characters across all text items         |
| First frame     | `image_url` | `first_frame`, or omit the role | 1 image                                                |
| Last frame      | `image_url` | `last_frame`                    | 1 image                                                |
| Reference image | `image_url` | `reference_image`               | 9 images                                               |
| Reference video | `video_url` | `reference_video`               | 3 videos                                               |
| Reference audio | `audio_url` | `reference_audio`               | 3 audio files; also include a reference image or video |

<Warning>
  Do not mix first- or last-frame inputs with reference inputs in the same request. Each `content` item must contain exactly one payload that matches its `type`.
</Warning>

### Control the first and last frames

Use `first_frame` and `last_frame` when you want the video to interpolate between two images.

```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"
  }'
```

### Generate with reference media

Reference inputs help preserve a subject, motion style, or sound. Reference audio cannot be the only media input.

```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"
  }'
```

## Request settings

| Field            | Required               | Supported values                                                      |
| ---------------- | ---------------------- | --------------------------------------------------------------------- |
| `model`          | Yes                    | `MiniMax-H3`                                                          |
| `content`        | Yes                    | Text plus optional frame or reference media                           |
| `resolution`     | Yes                    | `768P` or `2K`; values are case-sensitive                             |
| `duration`       | Yes                    | An integer from `4` through `15` seconds                              |
| `ratio`          | For text-only requests | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `adaptive` with media |
| `aigc_watermark` | No                     | `true` or `false`                                                     |

When a request contains media and omits `ratio`, Flatkey uses `adaptive`. A text-only request must explicitly use a non-`adaptive` ratio.

## Understand task results

| `status`      | Meaning                                                                  |
| ------------- | ------------------------------------------------------------------------ |
| `queued`      | The task is waiting to run.                                              |
| `in_progress` | The video is being generated. Read `progress` for a value from 0 to 100. |
| `completed`   | The video is ready at `metadata.url`.                                    |
| `failed`      | Generation failed. Read `error.code` and `error.message`.                |

For H3 video responses, the shared usage field names represent seconds:

* `usage.completion_tokens` is the generated output duration.
* `usage.total_tokens` is the total billable duration, including reference-video input time.

These values are seconds, not language-model tokens. Check **Usage Logs** in the [Flatkey Console](https://console.flatkey.ai/usage-logs/common) for the final charge.

## Current limitations

* `callback_url` is not supported. Poll the task status instead.
* Task listing, cancellation, deletion, regeneration, and remix are not supported.
* `MiniMax-H3-Context-IR` is not supported.
* Remote media URLs must remain reachable while the task is being processed.

| Error code                 | What to check                                                               |
| -------------------------- | --------------------------------------------------------------------------- |
| `invalid_duration`         | Set `duration` from `4` through `15`.                                       |
| `invalid_resolution`       | Use exactly `768P` or `2K`.                                                 |
| `invalid_ratio`            | Use a supported ratio. Text-only requests cannot omit it or use `adaptive`. |
| `invalid_content`          | Check the prompt, roles, media limits, and incompatible input combinations. |
| `unsupported_callback_url` | Remove `callback_url` and poll the task.                                    |