Generate MiniMax H3 videos with 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.

Flexible inputs

Generate from text, frame images, or reference images, videos, and audio.

One async workflow

Create with POST /v1/videos, poll with GET /v1/videos/{task_id}, and download from metadata.url.

Use this header for task creation and status requests:

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.

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

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

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

{
  "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.

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

$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

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

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.

Control the first and last frames

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

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.

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

Quick Start

Code

Mainstream AI Tools

Media Generation

Popular models

Dashboard

Reference

Generate MiniMax H3 videos with Flatkey

Flexible inputs

One async workflow

Create your first H3 video

1. Submit a text-to-video task

2. Poll and download the result

Choose your inputs

Control the first and last frames

Generate with reference media

Request settings

Understand task results

Current limitations

Flexible inputs

One async workflow

​Create your first H3 video

​1. Submit a text-to-video task

​2. Poll and download the result

​Choose your inputs

​Control the first and last frames

​Generate with reference media

​Request settings

​Understand task results

​Current limitations

Create your first H3 video

1. Submit a text-to-video task

2. Poll and download the result

Choose your inputs

Control the first and last frames

Generate with reference media

Request settings

Understand task results

Current limitations