Hailuo API: panduan MiniMax H3 dengan Python dan uji 3 mode video

Hailuo API adalah API video dari MiniMax, dan modelnya saat ini MiniMax H3 (MiniMax-H3), generasi setelah Hailuo 01 dan 02. Setiap panggilan berjalan asinkron: buat tugas, periksa statusnya, unduh MP4. Pada 26 Oktober 2026, klip 5 detik 768P kami memakan waktu 35 sampai 42 detik di ketiga mode, dan semuanya datang dengan suara.

Jawaban singkat

• Model: MiniMax-H3 di API MiniMax, diumumkan 31 Juli 2026 (catatan rilis); minimax-h3 di OmniaKey, satu id untuk ketiga jenis tugas (dokumentasi video).
• Pengaturan: resolution (wajib) berisi "768P" atau "2K", duration 4 sampai 15 detik bulat, aspect_ratio (dokumentasi video).
• Biaya: $0.08 per detik pada 768P, $0.40 untuk 5 detik, $0.13 pada 2K, harga daftar MiniMax (harga, diperiksa 26 Oktober 2026); tarif OmniaKey ada di halaman model.
• Waktu dan suara: 35 sampai 42 detik per klip, semuanya dengan suara stereo; referensi pembuatan V2 tidak mencantumkan tombol untuk mematikan suara (referensi pembuatan).

Apakah ada Hailuo API resmi?

Ada. MiniMax menjalankannya di platform.minimax.io, dan model yang ada di sana saat ini adalah MiniMax H3 dengan id MiniMax-H3 (halaman model, diperiksa 26 Oktober 2026).

Pengumuman MiniMax menyebut H3 sebagai generasi setelah Hailuo 01 dan Hailuo 02 (pengumuman). Model lama masih ada di API sebagai MiniMax-Hailuo-2.3 dan MiniMax-Hailuo-02 (referensi V1).

Namanya berubah dari halaman ke halaman. Dokumentasi MiniMax menulis "MiniMax H3", deskripsi model di API menulis "Hailuo-03" (referensi pembuatan), dan aplikasi Hailuo AI, tempat pengumuman menyuruh orang mencoba, menulis "Hailuo 3.0" (aplikasi). "Hailuo 3" bukan nama resmi.

Kunci dibuat di Account > API Keys, dan penagihannya sesuai pemakaian (FAQ API). Paket video MiniMax mencakup model lama, bukan H3 (harga).

MiniMax mencantumkan empat varian H3 (referensi pembuatan):

Di API MiniMax sendiri, satu panggilan terdiri dari tiga langkah (panduan video):

• POST https://api.minimax.io/v2/video_generation mengembalikan task_id (referensi pembuatan).
• Periksa GET /v2/query/video_generation/{task_id} sampai succeeded, lalu unduh content.url (referensi kueri).
• Hanya tugas 7 hari terakhir yang bisa diperiksa, dan MiniMax tidak mengumumkan berapa lama URL unduhan berlaku (referensi kueri).

V1 (Hailuo 2.3 dan 02) mengirim id tugas sebagai parameter ?task_id=, bukan bagian dari path, jadi pisahkan kedua alur ini (referensi V1).

OmniaKey menjual akses API ke MiniMax H3, jadi contoh di sini dijalankan lewat sana. Alurnya sama: POST https://api.omniakey.com/v1/media/tasks dengan header Idempotency-Key mengembalikan 202 dan sebuah id, lalu Anda memeriksa GET /v1/media/tasks/{id} (ringkasan media). Alur yang sama menjalankan Grok Imagine Video di panduan Grok Imagine Video API. Semua harga di bawah adalah harga daftar MiniMax.

Parameter apa yang bisa diatur?

• resolution wajib; 1080P dan 4K gagal dengan 400 model_price_error (dokumentasi video), dan V2 tidak punya 1080P untuk H3 (referensi pembuatan). Ketiga mode dijalankan pada 768P dan 2K tidak kami uji.
• duration berkisar 4 sampai 15 detik bulat (dokumentasi video); MiniMax-H3-Max mulai dari 5 dan menolak 4 (referensi pembuatan).
• aspect_ratio menerima adaptive, 16:9, 9:16, 1:1, 4:3, 3:4, atau 21:9 (dokumentasi video). Di API MiniMax, teks ke video membutuhkan rasio tetap dan gambar ke video mengikuti bentuk gambarnya (referensi pembuatan). Pada uji gambar ke video kami tidak mengisi rasio, dan klip tetap memakai bentuk gambar aslinya, 1376×768.
• input.media[] menerima first_frame dan last_frame opsional untuk gambar ke video, atau reference_image, reference_video, dan reference_audio untuk referensi ke video. Kedua jenis tidak bisa dicampur, dan referensi audio butuh referensi gambar atau video di sampingnya (dokumentasi video). Setiap entri berupa type dan url, entah tautan HTTPS publik atau data URI. OmniaKey membatasi seluruh permintaan pada 1 MiB termasuk Base64 (ringkasan media), jadi skrip mengirim JPEG 1024 piksel.
• Prompt ditaruh di input.prompt (dokumentasi video), sampai 7,000 karakter (panduan video). Suara yang Anda inginkan juga ditulis di sana.

Bagaimana memanggil Hailuo API dari Python?

Anda butuh Python 3 dan requests, dengan kunci di variabel lingkungan.

pip install requests
export OMNIAKEY_API_KEY="your-key"
python hailuo_h3.py t2v   # or i2v (needs bicycle.jpg) or r2v (needs robot.jpg)

Satu-satunya argumen adalah t2v, i2v, atau r2v; proses yang butuh gambar membaca bicycle.jpg atau robot.jpg dari folder yang sama.

Berikut skrip yang kami jalankan, tanpa perubahan:

import base64
import os
import sys
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

DRUMMER = (
    "A street drummer plays a fast rhythm on upturned plastic buckets on a rainy city sidewalk "
    "at night. Neon signs reflect in the puddles and a few people with umbrellas walk past "
    "behind him. The camera slowly pushes in from a medium shot to a close-up of his hands and "
    "drumsticks. Realistic, handheld documentary look, with the sound of rain and drumming."
)
BICYCLE = (
    "A gentle breeze moves the daisies in the basket and a few petals drift down to the "
    "cobblestones. The camera slowly pushes in toward the basket. The bicycle and the wall "
    "stay exactly as they are."
)
ROBOT = (
    "The small orange robot from the reference image waters potted plants on a sunny "
    "apartment balcony with a red watering can. Medium shot, slow sideways camera move, "
    "city rooftops in the background."
)


def data_uri(path):
    # A local JPEG sent inline. The whole request must stay under 1 MiB, so keep it small.
    with open(path, "rb") as f:
        return "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()


def make_video(operation, prompt, parameters, media, out):
    task_input = {"prompt": prompt}
    if media:
        task_input["media"] = media

    # 1. Create the task. Reuse the same Idempotency-Key only when retrying this exact request.
    resp = requests.post(
        API,
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={
            "model": "minimax-h3",
            "type": "video",
            "operation": operation,
            "input": task_input,
            "parameters": parameters,
        },
        timeout=60,
    )
    resp.raise_for_status()
    task = resp.json()
    print(operation, "task:", task["id"])

    # 2. Poll the same task. Slow is not failed: never resubmit, keep polling this id.
    deadline = time.time() + 15 * 60
    while task["status"] in ("queued", "processing"):
        if time.time() > deadline:
            raise SystemExit(f"still {task['status']}: poll {task['id']} again later")
        time.sleep(5)
        task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] != "succeeded":
        raise SystemExit(f"{operation} ended {task['status']}: {task.get('error')}")

    # 3. Download the clip now: the signed URL lasts about an hour.
    asset = task["assets"][0]
    with open(out, "wb") as f:
        f.write(requests.get(asset["url"], timeout=120).content)
    print("saved", out, asset["byte_size"], "bytes")


mode = sys.argv[1] if len(sys.argv) > 1 else "t2v"
if mode == "t2v":
    make_video(
        "text_to_video", DRUMMER,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        None, "drummer.mp4",
    )
elif mode == "i2v":
    make_video(
        "image_to_video", BICYCLE,
        {"resolution": "768P", "duration": 5},
        [{"type": "first_frame", "url": data_uri("bicycle.jpg")}], "bicycle.mp4",
    )
elif mode == "r2v":
    make_video(
        "reference_to_video", ROBOT,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        [{"type": "reference_image", "url": data_uri("robot.jpg")}], "robot.mp4",
    )

Keluaran pada 27 Oktober 2026:

$ python hailuo_h3.py t2v
text_to_video task: task_V5TXAJG7n3ny42imJNqgTXRL4L8PGStd
saved drummer.mp4 4612510 bytes
$ python hailuo_h3.py i2v
image_to_video task: task_c4m3wHmF79Cmq7ZhDrTnCyt8SmIaW1ls
saved bicycle.mp4 4705286 bytes
$ python hailuo_h3.py r2v
reference_to_video task: task_dqx1TYA7u0znN5PFTl9tbfdWgtbBUbKd
saved robot.mp4 5630121 bytes

Setiap proses memakan waktu 47 sampai 60 detik dari mulai sampai file tersimpan.

Simpan id tugas. Tugas yang lambat bukan berarti gagal, jadi periksa id yang sama alih-alih mengirim ulang (ringkasan media). URL unduhan bertanda tangan berlaku sekitar satu jam dan catatan tugas 24 jam, jadi simpan file segera atau periksa ulang untuk URL baru. Unduhannya sendiri tidak butuh kunci API.

Apa yang dikembalikan ketiga mode

Ketiga klip berasal dari tiga tugas pada 26 Oktober 2026, dengan isi permintaan yang persis seperti di skrip.

Setiap klip adalah MP4, H.264, 24 fps, 5.17 detik, dengan audio AAC stereo 32 kHz; usage berisi output_seconds: 5.

Teks ke video: penabuh drum jalanan

Prompt-nya adalah DRUMMER di skrip.

Yang kami lihat:

• Trotoar basah di malam hari, neon merah dan biru terpantul di aspal, mobil terparkir, dan penabuh drum berjaket hitam berkerudung membungkuk di atas ember biru yang dibalik. Kerudung menutupi wajah sepanjang klip.
• Kamera mendekat dari bidikan lebar ke bidikan dekat tangan, stik yang bergerak, dan permukaan ember, sementara seseorang berpayung lewat di belakang.
• Huruf pada papan neon tidak membentuk kata sungguhan. Pukulan drum menguat mendekati akhir, tetapi hujan tidak jelas terdengar.

Yang perlu diubah: kalau butuh wajah, tambahkan "hood down, face visible"; kalau hujan harus terdengar, beri satu kalimat suara khusus untuk hujan.

Gambar ke video: bingkai pertama tetap

Bingkai pertama adalah gambar diam yang kami buat dengan Nano Banana 2.1; prompt-nya BICYCLE dan hanya menjelaskan gerakan.

Yang kami lihat:

• Bingkai pertama sama dengan gambar diam: sepeda merah yang sama, dinding plester kuning, daun jendela, tanaman dalam pot, dan batu paving.
• Kamera mendekat sampai keranjang bunga daisy putih memenuhi bingkai, dan sepeda serta dinding menjaga bentuknya sampai akhir.
• Pada bingkai yang kami periksa, kami tidak melihat kelopak jatuh. Suaranya melodi piano solo yang lambat, padahal prompt tidak menyebut suara atau musik.

Yang perlu diubah: jelaskan hanya gerakan dan suara, karena tampilan sudah ditentukan gambar diam, lalu buat gambar diam dalam bentuk yang Anda inginkan untuk klipnya.

Referensi ke video: satu gambar menjaga karakter

Referensinya satu gambar robot oranye kecil yang dibuat dengan Nano Banana 2.1; prompt-nya ROBOT.

Yang kami lihat:

• Robot yang sama: tubuh bulat oranye, mata kaca biru bulat, antena pendek dengan bola di ujungnya, dan cakram bulat di sisi kepala, sekarang di balkon cerah dengan pot bunga dan herbal.
• Ia menuang air dari ember penyiram merah, aliran air terlihat sekitar 1 detik, dan kamera bergeser sedikit ke samping.
• Suaranya air mengalir dan memercik yang mulai tepat sebelum aliran muncul, tanpa musik.

Yang perlu diubah: karakternya tidak perlu diperbaiki. Agar tetap sama di beberapa klip, pakai gambar referensi yang sama setiap kali.

Suara: jelaskan, atau H3 yang memilih

Saat prompt tidak menyebut suara, H3 yang memilih: air untuk robot, yang cocok dengan penyiraman, dan piano untuk sepeda. Jelaskan suara yang Anda butuhkan di prompt. Referensi pembuatan V2 tidak mencantumkan tombol untuk mematikan suara (referensi pembuatan), jadi untuk klip tanpa suara, buang treknya setelahnya:

ffmpeg -i drummer.mp4 -an -c copy drummer-silent.mp4

Perintah itu menulis salinan berisi video H.264 saja, tetap 5.17 detik dan tanpa pengodean ulang.

Kesalahan apa yang akan muncul?

Kesalahan datang dari API tugas OmniaKey dan, pada panggilan langsung, dari MiniMax.

• 400 missing_idempotency_key: Header Idempotency-Key tidak ada. Tambahkan.
• 409 idempotency_key_reused: Kunci sama, isi baru. Kunci baru per tugas.
• 400 model_price_error: 1080P atau 4K. Pakai 768P atau 2K.
• 400 invalid_request: Isi atau parameter salah. Periksa parameternya.
• 403 model_not_allowed: Kunci tidak punya model ini. Periksa akses kunci.
• 503 no_available_channel: Model tidak tersedia sekarang. Coba lagi nanti.
• provider_submit_uncertain: Ditolak saat pengiriman. Pakai input.prompt, periksa media.
• Tugas failed: Pembuatan gagal. Baca error.

Tugas yang gagal atau dibatalkan dikembalikan dananya (ringkasan media). Di API MiniMax sendiri (kode kesalahan, diperiksa 26 Oktober 2026):

• MiniMax mengirim status HTTP yang sesuai dengan setiap kode, misalnya 401 dengan 1004 dan 400 dengan 2013 (referensi pembuatan).
• H3 di V2 mengizinkan 300 permintaan per menit dan 30 tugas berjalan bersamaan (batas laju).

Berapa biaya Hailuo API?

MiniMax menagih H3 per detik video keluaran, menurut varian dan resolusi (halaman harga, diperiksa 26 Oktober 2026):

Dengan harga itu: 5 detik pada 768P seharga $0.40, 10 detik pada 2K $1.30, dan 15 detik pada 2K $1.95.

• Lima gambar masukan pertama per tugas gratis (2 pada Max), setiap gambar tambahan $0.04 pada H3, dan masukan audio gratis. Video masukan ditagih per detik, dan pada Max satu detik masukan ($0.143 pada 768P) lebih mahal daripada satu detik keluaran. Untuk varian dan resolusi yang sama, ketiga jenis tugas berbiaya sama.
• H3 hanya bayar sesuai pemakaian, dan paket video MiniMax tidak mencakupnya. Angka per detik pada paket aplikasi Hailuo AI adalah kredit aplikasi, bukan harga API (aplikasi).
• Platform China MiniMax punya daftar harga sendiri dalam yuan, jadi jangan mengonversi yang satu ke yang lain (harga China, diperiksa 26 Oktober 2026).
• Di OmniaKey, tugas video ditagih per detik keluaran saat dibuat, dan tugas yang gagal atau dibatalkan dikembalikan dananya (ringkasan media).

Tarif OmniaKey saat ini ada di halaman model MiniMax H3; bentuk permintaannya ada di dokumentasi API video.

Pertanyaan umum

Apakah Hailuo API gratis?

Di API MiniMax sendiri, tidak: halaman harga, mulai cepat, dan FAQ tidak menampilkan uji coba gratis atau kredit untuk H3 (diperiksa 26 Oktober 2026). Yang gratis hanya lima gambar masukan pertama per tugas dan masukan audio (harga), dan kredit aplikasi Hailuo AI tidak berlaku sebagai kredit API.

Apa bedanya Hailuo 2.3 dan MiniMax H3?

Hailuo 2.3 berjalan di V1: 6 atau 10 detik, sampai 1080P, ditagih per video, dengan harga daftar MiniMax $0.28 untuk 6 detik pada 768P (harga, referensi V1). H3 berjalan di V2: 4 sampai 15 detik, 768P atau 2K, ditagih per detik, dengan suara stereo (referensi pembuatan, halaman model). MiniMax masih mencantumkan keduanya (FAQ model).

Apa itu MiniMax H3 Max?

Ini rilis bersama MiniMax dan fal.ai, yang dilatih lanjut oleh fal.ai di atas H3 untuk kecepatan (panduan video). Ia membuat klip 480P atau 768P berdurasi 5 sampai 15 detik, dan extra.prompt_expansion_mode menerima disabled, balanced (bawaan), atau quality (referensi pembuatan). Soal referensi, halaman MiniMax tidak sependapat: panduan video dan FAQ model hanya mencantumkan teks ke video serta gambar ke video, sedangkan referensi pembuatan dan halaman harga juga mencantumkan referensi ke video.

Bisakah MiniMax H3 dijalankan sendiri?

Bisa, di luar beberapa wilayah. Bobotnya ada di Hugging Face (MiniMaxAI/MiniMax-H3) dan GitHub (MiniMax-AI/MiniMax-H3) di bawah MiniMax H3 Community License Agreement, lisensi buatan sendiri (Hugging Face, GitHub). Pada revisi lisensi yang diperiksa 26 Agustus 2026, Amerika Serikat, Uni Eropa, Inggris, dan Korea Selatan termasuk wilayah yang dikecualikan dan butuh lisensi terpisah (panduan penyebaran lokal).

Catatan pembaruan

27 Oktober 2026: versi pertama, dengan klip yang dibuat pada 26 Oktober 2026.