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

# FlatKeyでMiniMax H3動画を生成する

> Flatkey経由でテキストまたは参照メディアからMiniMax H3動画タスクを作成し、ステータスをポーリングして完成したMP4をダウンロードします。

ベース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. テキストから動画へのタスクを送信する

`MiniMax-H3` モデルとテキストプロンプトを指定して `POST /v1/videos` を送信します。テキストのみのリクエストには、`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` の両方に公開タスクIDが含まれます:

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

返された `task_...` の値を保存してください。後でタスクを確認するために必要です。

### 2. 結果をポーリングしてダウンロードする

`status` が `completed` または `failed` になるまで `GET /v1/videos/{task_id}` をポーリングします。`completed` になったら、`metadata.url` から一時ダウンロード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を持っている人は誰でも有効期限が切れるまで生成された動画にアクセスできます。プライベートとして扱い、ログに記録・公開・共有しないでください。動画を速やかにダウンロードして、ご自身のストレージに保存してください。タスククエリを繰り返しても、期限切れの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` に対応するペイロードを1つだけ含める必要があります。
</Warning>

### 最初と最後のフレームを制御する

2枚の画像の間で動画を補間させたい場合は、`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` | 動画を生成中です。0から100の値を `progress` で確認できます。              |
| `completed`   | 動画は `metadata.url` で準備できています。                       |
| `failed`      | 生成に失敗しました。`error.code` と `error.message` を確認してください。 |

H3動画のレスポンスでは、共有の使用量フィールド名は秒を表します:

* `usage.completion_tokens` は生成された出力の長さです。
* `usage.total_tokens` は参照動画の入力時間を含む、合計請求対象の長さです。

これらの値は秒であり、言語モデルのトークンではありません。最終的な請求については、[Flatkey Console](https://console.flatkey.ai/usage-logs/common) の **Usage Logs** を確認してください。

## 現在の制限事項

* `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` を削除してタスクをポーリングしてください。                           |