Panduan API MiniMax H3: Integrasi PoYo, Harga, dan Prompt

Dengan API MiniMax H3 dari PoYo, Anda dapat membuat video 2K berdurasi 5–15 detik dari teks, frame awal dan akhir, atau media referensi. Tanpa media referensi, video 5 detik memiliki perkiraan biaya 105 kredit ($0.525).

Panduan ini dimulai dengan permintaan pertama, lalu membahas biaya, mode input, contoh Python dan Node.js, serta prompt untuk berbagai adegan. Semua endpoint dan harga dalam panduan ini berlaku untuk PoYo.

Mulai cepat: kirim tugas dan ambil video

1. Kirim tugas video 5 detik

Dapatkan API key dari konsol PoYo, ganti YOUR_POYO_API_KEY di bawah, lalu jalankan perintah di terminal atau server. Simpan kunci di sisi server; jangan memasukkannya ke kode browser atau repositori publik.

Dalam permintaan PoYo, nilai model untuk MiniMax H3 adalah hailuo-03. Contoh berikut mengirim tugas pembuatan video berbayar.

export POYO_API_KEY="YOUR_POYO_API_KEY"

curl --fail-with-body --max-time 30 \
  --request POST 'https://api.poyo.ai/api/generate/submit' \
  --header "Authorization: Bearer ${POYO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "hailuo-03",
    "input": {
      "prompt": "A golden retriever walks through a sunlit autumn park. One slow tracking shot, natural movement, warm afternoon light.",
      "duration": 5,
      "resolution": "2K",
      "aspect_ratio": "16:9"
    }
  }'

Setelah pengiriman berhasil, baca ID tugas dari data.task_id. Berikut contoh struktur respons dengan ID tugas pengganti:

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "YOUR_TASK_ID"
  }
}

2. Periksa hasil tugas

Isi TASK_ID dengan ID yang diterima dan gunakan API key yang sama:

TASK_ID="YOUR_TASK_ID"

curl --fail-with-body --max-time 30 \
  --request GET "https://api.poyo.ai/api/generate/status/${TASK_ID}" \
  --header "Authorization: Bearer ${POYO_API_KEY}"

Pengiriman berhasil berarti tugas telah diterima; Anda masih perlu menunggu video selesai dibuat. Nilai data.status dalam respons pemeriksaan memiliki empat kemungkinan:

Status	Arti	Langkah berikutnya
not_started	Menunggu diproses	Periksa lagi nanti
running	Sedang dibuat	Periksa lagi nanti
finished	Pembuatan selesai	Baca data.files[].file_url
failed	Pembuatan gagal	Periksa data.error_message dan hentikan polling

Berikut contoh respons setelah selesai. URL dan waktunya hanya ilustrasi:

{
  "code": 200,
  "data": {
    "task_id": "YOUR_TASK_ID",
    "status": "finished",
    "credits_amount": 105,
    "files": [
      {
        "file_url": "https://example.com/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-09-22T08:30:00",
    "progress": 100,
    "error_message": null
  }
}

Lihat definisi kolom dan contoh respons status lainnya di dokumentasi pemeriksaan tugas PoYo. Jika pemeriksaan gagal sementara atau batas waktu tunggu tercapai, simpan ID tugas dan periksa lagi nanti; jangan otomatis mengirim tugas berbayar baru.

Cara menghitung biaya MiniMax H3 di PoYo

Harga berikut diperiksa pada 21 September 2026. Semua nominal dalam USD, dengan konversi 1 kredit = $0.005. Sebelum membuat video dalam jumlah besar, pastikan harga terbaru di halaman model.

Komponen biaya	Kredit	USD
Durasi video yang dihasilkan	21 kredit/detik	$0.105/detik
Durasi video referensi input	21 kredit/detik	$0.105/detik
5 gambar referensi pertama per pembuatan	0	$0
Setiap gambar referensi mulai gambar ke-6	6.4 kredit	$0.032

Perkiraan kredit = 21 × (detik output + detik video referensi yang ditagihkan) + 6.4 × jumlah gambar referensi yang melebihi 5. Jika jumlah gambar referensi 5 atau kurang, biaya tambahan gambar adalah 0. Kalikan perkiraan kredit dengan $0.005 untuk biaya dalam USD. Untuk video referensi dengan pecahan detik, penagihan menggunakan durasi yang ditentukan server.

Contoh	Perkiraan kredit	Perkiraan USD
Membuat 5 detik tanpa media referensi	105	$0.525
Membuat 10 detik tanpa media referensi	210	$1.05
Membuat 15 detik tanpa media referensi	315	$1.575
Membuat 10 detik + video referensi 5 detik + 7 gambar referensi	327.8	$1.639

Contoh terakhir dihitung dengan 21 × (10 + 5) + 6.4 × (7 − 5). Biaya ini berlaku per pembuatan; jika satu shot memerlukan beberapa percobaan, masukkan biaya setiap pembuatan ke anggaran.

Memilih mode input dan media referensi

Kolom media yang dikirim menentukan mode input. Contoh mulai cepat di atas menggunakan teks ke video. Tambahkan kolom yang sesuai jika ingin menentukan frame awal dan akhir atau menggunakan media referensi.

Mode	Kolom input	Penggunaan
Teks ke video	prompt, tanpa URL media	Jelaskan adegan, aksi, dan gerakan kamera dengan kata-kata
Pembuatan dengan frame awal dan akhir	image_urls	Gambar pertama adalah frame awal; gambar kedua, jika ada, adalah frame akhir. Jangan sertakan aspect_ratio; rasio mengikuti frame pertama
Pembuatan dengan referensi multimodal	reference_image_urls, reference_video_urls, reference_audio_urls	Gabungkan gambar, video, dan audio; audio referensi memerlukan gambar atau video referensi

Jangan gabungkan image_urls dengan kolom reference_*_urls mana pun. Semua URL media harus dapat diakses publik dan diunduh langsung.

Batas parameter dan media

Batas berikut berasal dari dokumentasi API MiniMax H3 PoYo:

• prompt wajib diisi dan menerima hingga 2000 karakter.
• duration berupa bilangan bulat 5–15 detik, dengan nilai default 5; resolution hanya mendukung 2K.
• Teks ke video mendukung 21:9, 16:9, 4:3, 1:1, 3:4, dan 9:16, dengan default 16:9. Mode referensi juga mendukung adaptive dan menggunakannya sebagai default.
• Anda dapat mengirim hingga 9 gambar referensi, 3 video referensi, dan 3 klip audio referensi. Setiap video atau audio harus berdurasi 2–15 detik; total durasi video dan total durasi audio masing-masing tidak boleh melebihi 15 detik.

Contoh permintaan dengan frame awal dan akhir

Gunakan JSON berikut sebagai body POST /api/generate/submit. URL media di example.com adalah placeholder: ganti dengan media Anda sendiri yang dapat diunduh sebelum mengirim. Untuk hanya memakai frame awal, hapus URL kedua dari array.

{
  "model": "hailuo-03",
  "input": {
    "prompt": "The camera slowly moves through the temple doorway, starting at the entrance and ending inside the hall. Dust floats in the sunlight.",
    "duration": 6,
    "resolution": "2K",
    "image_urls": [
      "https://example.com/assets/temple-entrance.jpg",
      "https://example.com/assets/temple-interior.jpg"
    ]
  }
}

Contoh gabungan referensi gambar dan video

Gunakan Image 1 untuk menentukan penampilan karakter dan Video 1 untuk gerakan kamera yang diinginkan. Keduanya merujuk ke item pertama dalam array gambar dan array video. Ganti URL media dan periksa durasi video referensi sebelum mengirim.

{
  "model": "hailuo-03",
  "input": {
    "prompt": "Use Image 1 for the character appearance and outfit. The character turns and walks toward the window. Use Video 1 as the camera movement reference.",
    "duration": 8,
    "resolution": "2K",
    "aspect_ratio": "adaptive",
    "reference_image_urls": [
      "https://example.com/assets/character.png"
    ],
    "reference_video_urls": [
      "https://example.com/assets/camera-motion.mp4"
    ]
  }
}

Contoh integrasi Python dan Node.js

Contoh berikut memisahkan pengiriman dan pemeriksaan menjadi dua fungsi: dapatkan dan simpan ID tugas terlebih dahulu, lalu tunggu hasilnya. Jika pemeriksaan terputus, lanjutkan dengan ID awal tanpa membuat video lagi. Hanya pemeriksaan status yang mengulangi permintaan saat terjadi kesalahan koneksi, timeout, HTTP 429, atau beberapa kesalahan 5xx; pengiriman tidak diulang otomatis.

Kedua implementasi menunggu 10 detik antar-pemeriksaan, melakukan maksimal 60 pemeriksaan, dan menetapkan timeout 30 detik per permintaan. Total waktu tunggu juga mencakup durasi permintaan. Nilai ini adalah pengaturan aplikasi dalam contoh, bukan jaminan waktu pembuatan. Sesuaikan interval dan kebijakan percobaan ulang dengan kebutuhan aplikasi.

Python: kirim tugas dan periksa hasil secara berkala

Instal dependensi dengan python -m pip install requests dan atur variabel lingkungan POYO_API_KEY seperti dijelaskan di atas. Skrip Python sinkron ini memeriksa tugas pembuatan asinkron secara berkala.

import os
import time
import requests

BASE_URL = "https://api.poyo.ai"
API_KEY = os.environ["POYO_API_KEY"]
if not API_KEY.strip():
    raise ValueError("Set POYO_API_KEY")
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
RETRYABLE_HTTP = {429, 500, 502, 503, 504}


def response_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200 or not isinstance(body.get("data"), dict):
        raise RuntimeError(f"Unexpected API response: {body}")
    return body["data"]


def submit_h3(prompt, duration=5):
    response = requests.post(
        f"{BASE_URL}/api/generate/submit",
        headers=HEADERS,
        json={"model": "hailuo-03", "input": {
            "prompt": prompt, "duration": duration,
            "resolution": "2K", "aspect_ratio": "16:9",
        }},
        timeout=30,
    )
    task_id = response_data(response).get("task_id")
    if not isinstance(task_id, str) or not task_id:
        raise RuntimeError("Submission response is missing a task ID; check records instead of resubmitting automatically")
    return task_id


def wait_for_h3(task_id, max_polls=60):
    for _ in range(max_polls):
        time.sleep(10)
        try:
            response = requests.get(
                f"{BASE_URL}/api/generate/status/{task_id}",
                headers=HEADERS, timeout=30,
            )
        except (requests.Timeout, requests.ConnectionError):
            continue
        if response.status_code in RETRYABLE_HTTP:
            continue
        task = response_data(response)
        status = task.get("status")
        if status == "finished":
            for item in task.get("files") or []:
                if item.get("file_type") == "video" and item.get("file_url"):
                    return item["file_url"]
            raise RuntimeError(f"Task {task_id} finished, but the response has no video URL")
        if status == "failed":
            raise RuntimeError(f"Task {task_id} failed: {task.get('error_message')}")
        if status not in {"not_started", "running"}:
            raise RuntimeError(f"Task {task_id} returned an unknown status: {status}")
    raise TimeoutError(f"Query limit reached; keep the task ID and query again later: {task_id}")


if __name__ == "__main__":
    task_id = submit_h3("A golden retriever walks through a sunlit autumn park.")
    # In your application, save task_id to the database here before polling.
    print(f"Task ID: {task_id}", flush=True)
    print(wait_for_h3(task_id))

Untuk melanjutkan pemeriksaan, panggil langsung wait_for_h3(saved_task_id). Kesalahan HTTP seperti 401 dan 403, kesalahan API, atau respons yang tidak sesuai akan menghentikan polling; atasi penyebabnya sebelum melanjutkan.

Node.js: gunakan fetch bawaan

JavaScript berikut menggunakan fetch bawaan Node.js 20 atau lebih baru, sehingga tidak memerlukan dependensi klien HTTP. Simpan sebagai file .mjs dan jalankan di server.

const BASE_URL = 'https://api.poyo.ai';
const apiKey = process.env.POYO_API_KEY;
if (!apiKey?.trim()) throw new Error('Set POYO_API_KEY');
const headers = {
  Authorization: `Bearer ${apiKey}`,
  'Content-Type': 'application/json',
};
const retryableHttp = new Set([429, 500, 502, 503, 504]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function responseData(response) {
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const body = await response.json();
  if (body.code !== 200 || !body.data || typeof body.data !== 'object') {
    throw new Error(`Unexpected API response: ${JSON.stringify(body)}`);
  }
  return body.data;
}

export async function submitH3(prompt, duration = 5) {
  const response = await fetch(`${BASE_URL}/api/generate/submit`, {
    method: 'POST', headers,
    body: JSON.stringify({
      model: 'hailuo-03',
      input: { prompt, duration, resolution: '2K', aspect_ratio: '16:9' },
    }),
    signal: AbortSignal.timeout(30_000),
  });
  const data = await responseData(response);
  if (typeof data.task_id !== 'string' || !data.task_id) {
    throw new Error('Submission response is missing a task ID; check records instead of resubmitting automatically');
  }
  return data.task_id;
}

export async function waitForH3(taskId, maxPolls = 60) {
  for (let attempt = 0; attempt < maxPolls; attempt++) {
    await sleep(10_000);
    let response;
    try {
      response = await fetch(
        `${BASE_URL}/api/generate/status/${encodeURIComponent(taskId)}`,
        { headers, signal: AbortSignal.timeout(30_000) },
      );
    } catch (error) {
      if (error instanceof Error &&
          (error.name === 'TimeoutError' || error.name === 'TypeError')) {
        continue;
      }
      throw error;
    }
    if (retryableHttp.has(response.status)) {
      await response.body?.cancel();
      continue;
    }
    const task = await responseData(response);
    if (task.status === 'finished') {
      const video = task.files?.find((file) => file.file_type === 'video' && file.file_url);
      if (!video) throw new Error(`Task ${taskId} finished, but the response has no video URL`);
      return video.file_url;
    }
    if (task.status === 'failed') {
      throw new Error(`Task ${taskId} failed: ${task.error_message || 'No error details provided'}`);
    }
    if (!['not_started', 'running'].includes(task.status)) {
      throw new Error(`Task ${taskId} returned an unknown status: ${task.status}`);
    }
  }
  throw new Error(`Query limit reached; keep the task ID and query again later: ${taskId}`);
}

const taskId = await submitH3('A golden retriever walks through a sunlit autumn park.');
// In your application, save taskId to the database here before polling.
console.log(`Task ID: ${taskId}`);
console.log(await waitForH3(taskId));

Untuk melanjutkan pemeriksaan, ganti pemanggilan pengiriman dan pemeriksaan di akhir file dengan waitForH3(savedTaskId). Contoh polling ini sesuai untuk skrip atau tugas latar belakang. Dalam aplikasi web, kembalikan ID ke frontend dan pantau pembuatan di latar belakang agar satu permintaan halaman tidak terus menunggu.

Terima hasil melalui webhook

Anda juga dapat mengirim callback_url di tingkat teratas permintaan, sejajar dengan model dan input, misalnya https://your-domain.com/webhooks/poyo. PoYo mengirim hasil ke URL tersebut saat tugas berhasil atau gagal.

Penerima perlu mencocokkan ID tugas dengan catatan lokal dan menangani notifikasi duplikat berdasarkan ID agar operasi lanjutan tidak dijalankan berulang. Pekerjaan yang memakan waktu, seperti mengunduh atau mentranskode video, dapat dijalankan di latar belakang. Anda tetap dapat memakai pemeriksaan status untuk memverifikasi hasil selama integrasi callback.

Prompt dan contoh adegan

Jelaskan subjek dan aksi terlebih dahulu, lalu tambahkan gerakan kamera, latar, pencahayaan, dan suara. Saat memakai referensi, nyatakan peran Image 1, Video 1, atau Audio 1 agar satu media tidak diberi persyaratan yang saling bertentangan.

Empat contoh berbahasa Inggris berikut menunjukkan cara menulis prompt; belum disertai hasil pembuatan yang diuji. Istilah Inggris memudahkan penggunaan ulang, tetapi tidak berarti bahasa Inggris pasti lebih baik daripada bahasa Mandarin. Waktu dan instruksi mempertahankan penampilan adalah target; periksa hasil sebenarnya.

Iklan produk: 8 detik, mode gambar referensi

Letakkan gambar produk sebagai item pertama di input.reference_image_urls, atur duration: 8 dan aspect_ratio: "16:9", lalu gunakan teks berikut sebagai prompt. Ikuti struktur permintaan mode referensi di atas; hapus reference_video_urls jika tidak memerlukan video referensi.

Use Image 1 as the product reference. A clear glass perfume bottle rests on
wet black stone after rain. Preserve the bottle shape, cap, and label placement.
One continuous 8-second shot: begin close to the water droplets, then slowly
pull back to reveal the bottle in warm rim light. Realistic glass reflections,
no added text. Soft rain ambience.

Mulai dengan shot sederhana untuk memeriksa konsistensi botol dan label, lalu coba gerakan kamera mengorbit yang lebih kompleks.

Dialog karakter: 8 detik, mode gambar referensi

Letakkan gambar karakter sebagai item pertama di input.reference_image_urls, lalu atur duration: 8 dan aspect_ratio: "16:9". Dialog pendek memudahkan pemeriksaan sinkronisasi bibir, kecepatan bicara, dan penampilan karakter.

Use Image 1 as the character reference. An 8-second medium close-up of a pastry
chef in a quiet kitchen at sunrise. She looks into the camera and says:
"Every detail matters in baking." Natural breathing, a subtle smile,
soft window light. Preserve her face, hairstyle, and apron. A steady camera,
clear speech, quiet room tone.

Iklan gim vertikal: 10 detik, teks ke video

Atur duration: 10 dan aspect_ratio: "9:16". Segmen waktu menyatakan urutan aksi yang diinginkan; jika adegan terlalu padat, kurangi jumlah aksi dan karakter terlebih dahulu.

A 10-second vertical fantasy game trailer.
0-3s: An armored knight walks through a ruined stone gate.
3-6s: One creature charges; the knight blocks once with a shield.
6-9s: The camera rises to reveal the fortress walls.
9-10s: Hold the final composition.
Readable action, consistent armor, wind and impact sounds, no UI or captions.

Shot tracking berkelanjutan: 10 detik, teks ke video

Atur duration: 10 dan aspect_ratio: "16:9". Susun shot dengan satu subjek dan satu rute, lalu periksa pergantian shot, perubahan subjek, atau gerakan yang terputus.

One unbroken 10-second tracking shot follows a cyclist through a night market.
Begin behind the rear wheel, rise to shoulder height, then move alongside
without cutting. Wet pavement reflections, a clear path between stalls,
consistent bicycle geometry, no speed ramps or scene transitions.
Natural street ambience and bicycle tires rolling on wet pavement.

Pertanyaan umum dan pemecahan masalah integrasi

Bisakah saya langsung memakai format permintaan API milik MiniMax?

Contoh ini menggunakan POST /api/generate/submit dan GET /api/generate/status/{task_id} milik PoYo. Endpoint, pengenal model, dan struktur kolom dapat berbeda antarplatform; ikuti dokumentasi platform yang Anda gunakan.

Perlukah mengirim ulang tugas yang tetap berstatus not_started?

not_started berarti tugas menunggu diproses, bukan kegagalan. Simpan ID dan lanjutkan pemeriksaan. Jika batas waktu tunggu aplikasi tercapai, catat tugas dan periksa lagi nanti. Bila perlu, hubungi dukungan dengan ID tugas tersebut.

Bagaimana jika pengiriman timeout sebelum saya menerima ID tugas?

Timeout tidak membuktikan bahwa server belum menerima tugas. Periksa catatan tugas terlebih dahulu; bila perlu, hubungi dukungan dengan informasi seperti waktu pengiriman. Anda memerlukan ID tugas untuk memakai endpoint pemeriksaan status. Jangan menjadikan pengiriman ulang sebagai solusi untuk pemeriksaan yang gagal.

Bisakah gambar, video, dan audio digabungkan sebagai referensi?

Bisa, dalam mode referensi dengan batas jumlah dan durasi di atas. Audio referensi memerlukan gambar atau video referensi. Kolom ini tidak dapat digabungkan dengan image_urls untuk mode frame awal dan akhir.

Berapa biaya video 10 detik?

Dengan harga yang tercantum, tanpa media referensi, biayanya adalah 10 × 21 = 210 kredit, atau $1.05. Video referensi dan gambar referensi setelah 5 gambar pertama menambah biaya.

Sebelum integrasi ke aplikasi, pastikan URL media dapat diunduh langsung, simpan ID tugas, dan tetapkan batas pembuatan serta tugas bersamaan per pengguna. Sebelum menerbitkan video, periksa penampilan karakter, bentuk produk, teks, gerakan, dan suara agar sesuai dengan tujuan penggunaan.

Coba pembuatan di halaman model MiniMax H3, atau kunjungi halaman API key untuk mulai integrasi. Informasi lebih lanjut tersedia dalam ulasan MiniMax H3 dan perbandingan MiniMax H3 dengan Seedance 2.5.