Hailuo API: Python ile MiniMax H3 rehberi ve 3 video modu testi

Hailuo API, MiniMax video API ürünüdür ve güncel modeli Hailuo 01 ile 02 sonrasındaki nesil olan MiniMax H3 (MiniMax-H3). Her çağrı asenkron ilerler: görevi oluştur, durumunu sor, MP4 dosyasını indir. 26 Ekim 2026 tarihinde 5 saniyelik 768P kliplerimiz üç modda da 35 ile 42 saniye arasında döndü ve hepsi sesli geldi.

Kısa yanıt

• Model: MiniMax API üzerinde MiniMax-H3, 31 Temmuz 2026 tarihinde duyuruldu (sürüm notları); OmniaKey üzerinde minimax-h3 ve üç görev tipi için tek id (video dokümanları).
• Ayarlar: resolution (zorunlu) için "768P" veya "2K", duration için 4 ile 15 arası tam saniye, aspect_ratio (video dokümanları).
• Maliyet: 768P için saniyede $0.08, 5 saniye için $0.40, 2K için $0.13; bunlar MiniMax liste fiyatları (fiyatlar, 26 Ekim 2026 tarihinde kontrol edildi); OmniaKey tarifesi model sayfasında.
• Süre ve ses: klip başına 35 ile 42 saniye, hepsi stereo sesli; V2 oluşturma referansında sesi kapatacak bir anahtar yok (oluşturma referansı).

Resmi bir Hailuo API var mı?

Var. MiniMax bunu platform.minimax.io üzerinde sunuyor ve oradaki güncel model, id değeri MiniMax-H3 olan MiniMax H3 (modeller sayfası, 26 Ekim 2026 tarihinde kontrol edildi).

MiniMax duyurusu H3 modelini Hailuo 01 ve Hailuo 02 sonrasındaki nesil olarak tanıtıyor (duyuru). Eski modeller API içinde MiniMax-Hailuo-2.3 ve MiniMax-Hailuo-02 adlarıyla duruyor (V1 referansı).

Ad sayfadan sayfaya değişiyor. MiniMax dokümanları "MiniMax H3", API içindeki model açıklaması "Hailuo-03" (oluşturma referansı), duyurunun denemeye yönlendirdiği Hailuo AI uygulaması ise "Hailuo 3.0" yazıyor (uygulama). "Hailuo 3" resmi bir ad değil.

Anahtar Account > API Keys altında oluşturulur ve ücret kullanım kadar ödenir (API SSS). MiniMax video paketleri eski modelleri kapsıyor, H3 bunlara girmiyor (fiyatlar).

MiniMax dört H3 varyantı listeliyor (oluşturma referansı):

MiniMax kendi API üzerinde bir çağrı üç adımdan oluşur (video kılavuzu):

• POST https://api.minimax.io/v2/video_generation bir task_id döndürür (oluşturma referansı).
• GET /v2/query/video_generation/{task_id} adresi succeeded olana kadar sorgulanır, sonra content.url indirilir (sorgu referansı).
• Yalnızca son 7 günün görevleri sorgulanabilir ve indirme adresinin ne kadar geçerli olduğunu MiniMax yayınlamıyor (sorgu referansı).

V1 (Hailuo 2.3 ve 02) görev id değerini yolun parçası olarak değil ?task_id= parametresi olarak gönderir, bu yüzden iki akışı ayrı tutun (V1 referansı).

OmniaKey MiniMax H3 için API erişimi satıyor, bu yüzden örnekleri onun üzerinden çalıştırdık. Akış aynı: Idempotency-Key başlığıyla POST https://api.omniakey.com/v1/media/tasks çağrısı 202 ve bir id döndürür, ardından GET /v1/media/tasks/{id} ile durum sorulur (medya genel bakış). Aynı akış Grok Imagine Video API rehberinde Grok Imagine Video için de çalışıyor. Aşağıdaki fiyatların hepsi MiniMax liste fiyatı.

Hangi parametreler ayarlanabilir?

• resolution zorunlu; 1080P ve 4K değerleri 400 model_price_error ile düşüyor (video dokümanları) ve V2 içinde H3 için 1080P yok (oluşturma referansı). Üç modu da 768P ile çalıştırdık, 2K denemedik.
• duration 4 ile 15 arası tam saniye (video dokümanları); MiniMax-H3-Max 5 ile başlıyor ve 4 değerini reddediyor (oluşturma referansı).
• aspect_ratio değerleri adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 veya 21:9 (video dokümanları). MiniMax API üzerinde metinden videoya sabit bir oran gerekiyor, görselden videoya ise görselin biçimini izliyor (oluşturma referansı). Görselden video denememizde oranı vermedik ve klip, görselin biçimini yani 1376×768 değerini korudu.
• input.media[] görselden videoda first_frame ve isteğe bağlı last_frame, referanstan videoda reference_image, reference_video ve reference_audio kabul ediyor. İki tür karıştırılamıyor ve ses referansının yanında bir görsel ya da video referansı gerekiyor (video dokümanları). Her giriş bir type ve bir url içeriyor; değer, herkese açık HTTPS adresi ya da data URI olabilir. OmniaKey tüm isteği Base64 dahil 1 MiB ile sınırlıyor (medya genel bakış), bu yüzden betik 1024 piksel JPEG gönderiyor.
• İstem input.prompt alanında duruyor (video dokümanları) ve 7,000 karaktere kadar çıkıyor (video kılavuzu). İstediğiniz sesi de oraya yazıyorsunuz.

Hailuo API Python'dan nasıl çağrılır?

Python 3 ve requests gerekiyor; anahtarı bir ortam değişkenine koyun.

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

Tek argüman t2v, i2v veya r2v. Görsel gereken çalışmalar aynı klasördeki bicycle.jpg ya da robot.jpg dosyasını okuyor.

Çalıştırdığımız betik aşağıda, tek karakteri değişmedi:

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",
    )

27 Ekim 2026 tarihli çıktı:

$ 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

Her çalışma başlangıçtan dosyanın kaydedilmesine kadar 47 ile 60 saniye sürdü.

Görev id değerini saklayın. Yavaş bir görev başarısız sayılmaz; yeniden göndermek yerine aynı id değerini sorgulamaya devam edin (medya genel bakış). İmzalı indirme adresi yaklaşık bir saat, görev kaydı 24 saat geçerli; dosyayı hemen kaydedin ya da yeni bir adres için tekrar sorgulayın. İndirme işlemi API anahtarı istemiyor.

Üç moddan ne geldi

Üç klip, 26 Ekim 2026 tarihindeki üç görevden, betikteki istek gövdeleriyle aynı şekilde çıktı.

Her klip MP4, H.264, 24 fps ve 5.17 saniyeydi; 32 kHz stereo AAC ses vardı ve usage alanında output_seconds: 5 yazıyordu.

Metinden videoya: sokak davulcusu

İstem, betikteki DRUMMER.

Ne gördük:

• Gece ıslak bir kaldırım, yerde kırmızı ve mavi neon yansımaları, park etmiş arabalar ve ters çevrilmiş mavi kovaların üstüne eğilmiş siyah kapüşonlu ceketli bir davulcu. Kapüşon yüzü baştan sona gizliyor.
• Kamera geniş açıdan ellerin, hareket eden bagetlerin ve kovaların üst yüzeyinin yakın planına doğru ilerliyor; arkada şemsiyeli biri geçiyor.
• Neon tabelalardaki harfler gerçek kelimeler oluşturmuyor. Davul vuruşları sona doğru güçleniyor ama yağmur seste belirgin değil.

Ne değiştirmeli: yüz gerekiyorsa "hood down, face visible" ekleyin; yağmurun duyulması gerekiyorsa ona ayrı bir ses cümlesi verin.

Görselden videoya: ilk kare yerinde kalıyor

İlk kare Nano Banana 2.1 ile yaptığımız sabit görsel; istem BICYCLE ve yalnızca hareketi anlatıyor.

Ne gördük:

• İlk kare sabit görselle aynı: aynı kırmızı bisiklet, sarı sıvalı duvar, panjurlar, saksılar ve arnavut kaldırımı.
• Kamera, beyaz papatyalı sepet kareyi doldurana kadar yaklaşıyor; bisiklet ve duvar baştan sona biçimini koruyor.
• Baktığımız karelerde yaprak düştüğünü görmedik. Ses yavaş bir solo piyano melodisi, oysa istemde ne sesten ne müzikten söz ediliyor.

Ne değiştirmeli: görünümü zaten sabit görsel belirlediği için yalnızca hareketi ve sesi anlatın; sabit görseli de klip hangi biçimde olacaksa o biçimde hazırlayın.

Referanstan videoya: tek görsel karakteri koruyor

Referans, Nano Banana 2.1 ile yaptığımız küçük turuncu robotun tek görseli; istem ROBOT.

Ne gördük:

• Aynı robot: turuncu yuvarlak gövde, yuvarlak mavi cam gözler, ucunda top olan kısa bir anten ve kafanın yanında yuvarlak bir disk; şimdi çiçek ve bitki saksılarıyla dolu güneşli bir balkonda.
• Kırmızı sulama kabından su döküyor, su akışı yaklaşık 1 saniyede görünüyor ve kamera hafifçe yana kayıyor.
• Ses, akan ve sıçrayan su; akış görünmeden hemen önce başlıyor ve müzik yok.

Ne değiştirmeli: karakter için düzeltme gerekmedi. Aynı karakteri birkaç klipte korumak için her seferinde aynı referans görseli kullanın.

Ses: ya siz yazın ya H3 seçsin

İstemde sesle ilgili bir şey yoksa H3 seçti: sulamaya uyan su sesi robot için, piyano ise bisiklet için. Gereken sesi istemde anlatın. V2 oluşturma referansında sesi kapatacak bir anahtar yok (oluşturma referansı), bu yüzden sessiz klip için ses kanalını sonradan çıkarın:

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

Bu komut yalnızca H.264 video içeren bir kopya yazar; süre 5.17 saniye kalır ve yeniden kodlama yapılmaz.

Hangi hatalarla karşılaşırsınız?

Hatalar OmniaKey görev API ürününden, doğrudan çağrıda ise MiniMax tarafından geliyor.

• 400 missing_idempotency_key: Idempotency-Key başlığı yok. Başlığı ekleyin.
• 409 idempotency_key_reused: Aynı anahtar, yeni gövde. Görev başına yeni anahtar.
• 400 model_price_error: 1080P veya 4K. 768P ya da 2K kullanın.
• 400 invalid_request: Gövde veya parametre hatalı. Parametreleri kontrol edin.
• 403 model_not_allowed: Anahtarın bu modele erişimi yok. Anahtar erişimini kontrol edin.
• 503 no_available_channel: Model şu anda kullanılamıyor. Sonra tekrar deneyin.
• provider_submit_uncertain: Gönderim sırasında reddedildi. input.prompt kullanın, materyali kontrol edin.
• Görev failed: Üretim başarısız. error alanını okuyun.

Başarısız ya da iptal edilen görevin ücreti iade edilir (medya genel bakış). MiniMax API ürününü doğrudan çağırırken durum şöyle (hata kodları, 26 Ekim 2026 tarihinde kontrol edildi):

• MiniMax her kodla birlikte karşılık gelen HTTP durumunu gönderiyor, örneğin 1004 ile 401, 2013 ile 400 (oluşturma referansı).
• V2 üzerinde H3 dakikada 300 istek ve aynı anda 30 çalışan görev kabul ediyor (hız sınırları).

Hailuo API ne kadar?

MiniMax H3 ücretini çıktı videosunun saniyesi üzerinden, varyant ve çözünürlüğe göre alıyor (fiyat sayfası, 26 Ekim 2026 tarihinde kontrol edildi):

Bu fiyatlarla 768P 5 saniye $0.40, 2K 10 saniye $1.30, 2K 15 saniye $1.95.

• Görev başına ilk 5 girdi görseli ücretsiz (Max için 2), sonraki her görsel H3 üzerinde $0.04 ve ses girdisi ücretsiz. Girdi videosu saniye üzerinden faturalanıyor ve Max üzerinde girdi saniyesi (768P için $0.143) çıktı saniyesinden pahalı. Aynı varyant ve çözünürlükte üç görev tipi de aynı fiyata geliyor.
• H3 yalnızca kullandıkça ödeme ile çalışıyor, MiniMax video paketleri bu modeli kapsamıyor. Hailuo AI uygulamasının planlarındaki saniye rakamları uygulama kredisi, API fiyatı değil (uygulama).
• MiniMax Çin platformunun yuan cinsinden ayrı bir fiyat listesi var, bu yüzden birini diğerine çevirmeyin (Çin fiyatları, 26 Ekim 2026 tarihinde kontrol edildi).
• OmniaKey üzerinde video görevi oluşturulurken çıktı saniyesi üzerinden ücret alınıyor, başarısız ya da iptal edilen görevde ücret iade ediliyor (medya genel bakış).

OmniaKey güncel tarifesi MiniMax H3 model sayfasında, istek biçimi ise video API dokümanlarında.

Sık sorulan sorular

Hailuo API ücretsiz mi?

MiniMax API ürününde değil: fiyat, hızlı başlangıç ve SSS sayfalarında H3 için ücretsiz deneme ya da kredi görünmüyor (26 Ekim 2026 tarihinde kontrol edildi). Ücretsiz olan tek şey görev başına ilk 5 girdi görseli ve ses girdisi (fiyatlar); Hailuo AI uygulamasının kredileri API kredisi olarak çalışmıyor.

Hailuo 2.3 ile MiniMax H3 arasındaki fark ne?

Hailuo 2.3 V1 üzerinde çalışıyor: 6 ya da 10 saniye, 1080P değerine kadar, video başına faturalama ve 768P 6 saniye için MiniMax liste fiyatı $0.28 (fiyatlar, V1 referansı). H3 V2 üzerinde çalışıyor: 4 ile 15 saniye, 768P veya 2K, saniye üzerinden faturalama ve stereo ses (oluşturma referansı, modeller sayfası). MiniMax ikisini de listeliyor (model SSS).

MiniMax H3 Max nedir?

MiniMax ile fal.ai ortak sürümü; fal.ai hız için H3 üzerinde ek eğitim yapmış (video kılavuzu). 480P ya da 768P çözünürlükte 5 ile 15 saniye arası klipler üretiyor ve extra.prompt_expansion_mode alanı disabled, balanced (varsayılan) veya quality değerlerini alıyor (oluşturma referansı). Referans kabul edip etmediği konusunda MiniMax sayfaları birbirini tutmuyor: video kılavuzu ve model SSS yalnızca metinden video ile görselden videoyu sayıyor, oluşturma referansı ve fiyat sayfası referanstan videoyu da sayıyor.

MiniMax H3 kendi sunucumda çalışır mı?

Bazı bölgelerin dışında çalışır. Ağırlıklar Hugging Face (MiniMaxAI/MiniMax-H3) ve GitHub (MiniMax-AI/MiniMax-H3) üzerinde, özel bir lisans olan MiniMax H3 Community License Agreement ile duruyor (Hugging Face, GitHub). 26 Ağustos 2026 tarihinde incelenen lisans sürümünde ABD, AB, Birleşik Krallık ve Güney Kore hariç tutulan bölgeler arasında ve ayrı lisans gerektiriyor (yerel kurulum kılavuzu).

Güncelleme kaydı

27 Ekim 2026: ilk sürüm; klipler 26 Ekim 2026 tarihinde üretildi.