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

# Buat video MiniMax H3 dengan Flatkey

> Buat tugas video MiniMax H3 dari teks atau media referensi, periksa statusnya, dan unduh MP4 yang sudah selesai melalui Flatkey.

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

Gunakan `MiniMax-H3` saat Anda membutuhkan teks-ke-video, kontrol frame pertama dan terakhir, atau referensi gambar, video, dan audio. Setiap permintaan mengikuti alur kerja asinkron yang sama: buat tugas, periksa statusnya, lalu unduh MP4 yang sudah selesai.

<CardGroup cols={2}>
  <Card title="Input yang fleksibel" icon="images">
    Buat dari teks, gambar frame, atau referensi gambar, video, dan audio.
  </Card>

  <Card title="Satu alur kerja async" icon="video">
    Buat dengan `POST /v1/videos`, periksa dengan `GET /v1/videos/{task_id}`, dan unduh dari `metadata.url`.
  </Card>
</CardGroup>

Gunakan header ini untuk permintaan pembuatan tugas dan pemeriksaan status:

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

Jaga kerahasiaan API key Anda. Jangan tempelkan ke log publik, halaman, atau tiket dukungan.

## Buat video H3 pertama Anda

### 1. Kirim tugas teks-ke-video

Kirim `POST /v1/videos` dengan model `MiniMax-H3` dan prompt teks. Permintaan hanya teks memerlukan rasio aspek eksplisit selain `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>

Respons berisi ID tugas publik di `id` dan `task_id`:

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

Simpan nilai `task_...` yang dikembalikan. Anda membutuhkannya untuk memeriksa tugas nanti.

### 2. Periksa dan unduh hasilnya

Periksa `GET /v1/videos/{task_id}` hingga `status` menjadi `completed` atau `failed`. Saat `completed`, baca URL unduhan sementara dari `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` adalah URL unduhan sementara. URL ini berfungsi tanpa header otorisasi Flatkey, sehingga siapa pun yang memilikinya dapat mengakses video yang dihasilkan hingga kedaluwarsa. Perlakukan sebagai privat, dan jangan dicatat, dipublikasikan, atau dibagikan. Unduh video segera dan simpan di penyimpanan Anda sendiri. Mengulangi kueri tugas tidak akan memperbarui URL yang sudah kedaluwarsa.

## Pilih input Anda

Setiap permintaan harus berisi item teks yang tidak kosong. Anda dapat menambahkan gambar frame atau media referensi untuk mengontrol hasilnya.

| Input            | `type`      | `role` yang diperlukan           | Batas                                                   |
| ---------------- | ----------- | -------------------------------- | ------------------------------------------------------- |
| Prompt           | `text`      | Jangan tetapkan role             | 7.000 karakter Unicode di semua item teks               |
| Frame pertama    | `image_url` | `first_frame`, atau abaikan role | 1 gambar                                                |
| Frame terakhir   | `image_url` | `last_frame`                     | 1 gambar                                                |
| Gambar referensi | `image_url` | `reference_image`                | 9 gambar                                                |
| Video referensi  | `video_url` | `reference_video`                | 3 video                                                 |
| Audio referensi  | `audio_url` | `reference_audio`                | 3 file audio; sertakan juga gambar atau video referensi |

<Warning>
  Jangan mencampur input frame pertama atau terakhir dengan input referensi dalam permintaan yang sama. Setiap item `content` harus berisi tepat satu payload yang sesuai dengan `type`-nya.
</Warning>

### Kontrol frame pertama dan terakhir

Gunakan `first_frame` dan `last_frame` saat Anda ingin video menginterpolasi antara dua gambar.

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

### Buat dengan media referensi

Input referensi membantu mempertahankan subjek, gaya gerakan, atau suara. Audio referensi tidak bisa menjadi satu-satunya input media.

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

## Pengaturan permintaan

| Field            | Diperlukan                  | Nilai yang didukung                                                       |
| ---------------- | --------------------------- | ------------------------------------------------------------------------- |
| `model`          | Ya                          | `MiniMax-H3`                                                              |
| `content`        | Ya                          | Teks ditambah frame opsional atau media referensi                         |
| `resolution`     | Ya                          | `768P` atau `2K`; nilai peka huruf besar-kecil                            |
| `duration`       | Ya                          | Bilangan bulat dari `4` hingga `15` detik                                 |
| `ratio`          | Untuk permintaan hanya teks | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, atau `adaptive` dengan media |
| `aigc_watermark` | Tidak                       | `true` atau `false`                                                       |

Saat permintaan berisi media dan `ratio` dihilangkan, Flatkey menggunakan `adaptive`. Permintaan hanya teks harus secara eksplisit menggunakan rasio selain `adaptive`.

## Memahami hasil tugas

| `status`      | Arti                                                                |
| ------------- | ------------------------------------------------------------------- |
| `queued`      | Tugas sedang menunggu untuk dijalankan.                             |
| `in_progress` | Video sedang dibuat. Baca `progress` untuk nilai dari 0 hingga 100. |
| `completed`   | Video siap di `metadata.url`.                                       |
| `failed`      | Pembuatan gagal. Baca `error.code` dan `error.message`.             |

Untuk respons video H3, nama field penggunaan bersama merepresentasikan detik:

* `usage.completion_tokens` adalah durasi output yang dihasilkan.
* `usage.total_tokens` adalah total durasi yang dapat ditagih, termasuk waktu input video referensi.

Nilai-nilai ini dalam satuan detik, bukan token model bahasa. Periksa **Usage Logs** di [Flatkey Console](https://console.flatkey.ai/usage-logs/common) untuk tagihan akhir.

## Keterbatasan saat ini

* `callback_url` tidak didukung. Periksa status tugas sebagai gantinya.
* Pencatatan, pembatalan, penghapusan, pembuatan ulang, dan remix tugas tidak didukung.
* `MiniMax-H3-Context-IR` tidak didukung.
* URL media jarak jauh harus tetap dapat diakses selama tugas sedang diproses.

| Kode error                 | Yang perlu diperiksa                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `invalid_duration`         | Tetapkan `duration` dari `4` hingga `15`.                                                                    |
| `invalid_resolution`       | Gunakan tepat `768P` atau `2K`.                                                                              |
| `invalid_ratio`            | Gunakan rasio yang didukung. Permintaan hanya teks tidak boleh menghilangkannya atau menggunakan `adaptive`. |
| `invalid_content`          | Periksa prompt, role, batas media, dan kombinasi input yang tidak kompatibel.                                |
| `unsupported_callback_url` | Hapus `callback_url` dan periksa tugas secara manual.                                                        |