MiniMax H3 API Rehberi: PoYo Entegrasyonu, Fiyatlar ve İstemler

PoYo MiniMax H3 API ile metinden, başlangıç ve bitiş karelerinden veya referans medyadan 5–15 saniyelik 2K videolar oluşturabilirsiniz. Referans medya kullanılmadığında 5 saniyelik bir videonun tahmini maliyeti 105 kredidir ($0.525).

Bu rehber ilk isteğinizle başlar; ardından fiyatları, giriş modlarını, Python ve Node.js örneklerini ve farklı sahneler için istemleri açıklar. Buradaki tüm uç noktalar ve fiyatlar PoYo için geçerlidir.

Hızlı başlangıç: görev gönderin ve videoyu alın

1. 5 saniyelik bir video görevi gönderin

PoYo konsolundan bir API anahtarı alın, aşağıdaki YOUR_POYO_API_KEY değerini değiştirin ve komutu terminalde veya sunucunuzda çalıştırın. Anahtarı sunucuda tutun; tarayıcı koduna ya da herkese açık depolara eklemeyin.

PoYo isteklerinde MiniMax H3 için model değeri hailuo-03 olmalıdır. Aşağıdaki örnek, ücretli bir video oluşturma görevi gönderir.

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

Başarılı gönderimden sonra görev kimliğini data.task_id alanından okuyun. Aşağıdaki örnek, yer tutucu görev kimliğiyle yanıt yapısını gösterir:

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

2. Görev sonucunu sorgulayın

Dönen görev kimliğini TASK_ID değişkenine atayın ve aynı API anahtarını kullanın:

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

Başarılı gönderim, görevin kabul edildiği anlamına gelir; videonun tamamlanmasını ayrıca beklemeniz gerekir. Sorgu yanıtındaki data.status alanı dört değer alabilir:

Tamamlanmış bir görevin yanıt örneği aşağıdadır. URL ve zaman bilgisi örnek amaçlıdır:

{
  "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
  }
}

Alan tanımları ve diğer durumlara ait yanıtlar için PoYo görev sorgulama belgelerine bakın. Sorgu geçici olarak başarısız olursa veya bekleme süreniz dolarsa görev kimliğini saklayıp daha sonra yeniden sorgulayın; otomatik olarak başka bir ücretli oluşturma isteği göndermeyin.

PoYo üzerinde MiniMax H3 nasıl ücretlendirilir?

Aşağıdaki fiyatlar 21 Eylül 2026 tarihinde kontrol edilmiştir. Tüm tutarlar USD cinsindedir ve 1 kredi = $0.005 olarak hesaplanmıştır. Toplu oluşturma öncesinde model sayfasından güncel fiyatları doğrulayın.

Tahmini kredi = 21 × (çıktı saniyesi + referans videonun ücretlendirilen saniyesi) + 6.4 × 5 adedi aşan referans görsel sayısı. En fazla 5 referans görsel kullanıldığında ek görsel ücreti 0 olur. USD maliyetini bulmak için tahmini krediyi $0.005 ile çarpın. Referans videoda kesirli saniyeler varsa sunucunun belirlediği ücretlendirme süresi kullanılır.

Son örneğin hesabı 21 × (10 + 5) + 6.4 × (7 − 5) şeklindedir. Bunlar tek bir oluşturmanın maliyetidir; bir çekim için birden fazla deneme gerekiyorsa bütçeye her oluşturmayı dahil edin.

Giriş modunu ve referans medyayı seçin

Gönderdiğiniz medya alanları giriş modunu belirler. Yukarıdaki hızlı başlangıç örneği metinden video oluşturur. Başlangıç ve bitiş kareleri belirtmek veya referans medya kullanmak istediğinizde ilgili alanları ekleyin.

image_urls alanını hiçbir reference_*_urls alanıyla birlikte kullanmayın. Tüm medya URL’leri herkese açık olmalı ve doğrudan indirmeye izin vermelidir.

Parametre ve medya sınırları

Aşağıdaki sınırlar PoYo MiniMax H3 API belgelerine dayanır:

• prompt zorunludur ve en fazla 2000 karakter kabul eder.
• duration, 5–15 saniye arasında bir tam sayıdır; varsayılanı 5’tir. resolution yalnızca 2K değerini destekler.
• Metinden video modu 21:9, 16:9, 4:3, 1:1, 3:4 ve 9:16 oranlarını destekler; varsayılanı 16:9 olur. Referans modu ayrıca adaptive değerini destekler ve varsayılan olarak kullanır.
• En fazla 9 referans görsel, 3 referans video ve 3 referans ses klibi gönderilebilir. Her video veya ses klibi 2–15 saniye olmalıdır; videoların toplam süresi ve seslerin toplam süresi ayrı ayrı 15 saniyeyi aşmamalıdır.

Başlangıç ve bitiş karesiyle istek örneği

Aşağıdaki JSON’u POST /api/generate/submit gövdesi olarak kullanın. example.com altındaki medya URL’leri yer tutucudur; göndermeden önce kendi indirilebilir medyanızla değiştirin. Yalnızca başlangıç karesini kullanmak için dizideki ikinci URL’yi kaldırın.

{
  "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"
    ]
  }
}

Görsel ve video referanslarını birleştiren örnek

Karakterin görünümü için Image 1, istenen kamera hareketi için Video 1 kullanın. Bunlar sırasıyla görsel dizisinin ve video dizisinin ilk öğesine karşılık gelir. Göndermeden önce URL’leri değiştirip referans videonun süresini kontrol edin.

{
  "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"
    ]
  }
}

Python ve Node.js entegrasyon örnekleri

Örnekler gönderim ve sorgulamayı iki işleve ayırır: önce görev kimliğini alıp kaydedin, sonra sonucu bekleyin. Sorgulama kesilirse yeniden video oluşturmadan aynı kimlikle devam edebilirsiniz. Bağlantı hataları, zaman aşımları, HTTP 429 ve belirli 5xx hatalarında yalnızca durum sorguları yeniden denenir; gönderim otomatik tekrarlanmaz.

Her iki uygulama sorgular arasında 10 saniye bekler, en fazla 60 sorgu yapar ve istek başına 30 saniyelik zaman aşımı kullanır. Dolayısıyla toplam bekleme süresi istek sürelerini de içerir. Bunlar örnek uygulama ayarlarıdır, oluşturma süresi garantisi değildir. Aralıkları ve yeniden deneme politikasını uygulamanıza göre ayarlayın.

Python: görev gönderme ve sonucu sorgulama

python -m pip install requests ile bağımlılığı kurun ve yukarıda açıklanan POYO_API_KEY ortam değişkenini ayarlayın. Bu senkron Python betiği, asenkron bir oluşturma görevini periyodik olarak sorgular.

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

Sorgulamaya devam etmek için doğrudan wait_for_h3(saved_task_id) çağırın. 401 ve 403 gibi HTTP hataları, API düzeyindeki hatalar veya beklenmeyen yanıtlar sorgulamayı durdurur; devam etmeden önce nedeni giderin.

Node.js: yerleşik fetch kullanımı

Aşağıdaki JavaScript, Node.js 20 veya üzerindeki yerleşik fetch işlevini kullanır; ek HTTP istemcisi bağımlılığı gerekmez. Kodu .mjs dosyasına kaydedip sunucuda çalıştırın.

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));

Sorgulamaya devam etmek için dosyanın sonundaki gönderim ve sorgu çağrılarını waitForH3(savedTaskId) ile değiştirin. Bu örnek betikler veya arka plan görevleri için uygundur. Web uygulamasında görev kimliğini ön yüze döndürün ve bir sayfa isteğini bekletmek yerine oluşturmayı arka planda takip edin.

Sonuçları webhook ile alma

Gönderim isteğinin en üst düzeyinde, model ve input ile aynı seviyede callback_url da verebilirsiniz; örneğin https://your-domain.com/webhooks/poyo. Görev başarılı olduğunda veya başarısızlıkla sonuçlandığında PoYo sonucu bu URL’ye gönderir.

Alıcı, görev kimliğini yerel kayıtlarla eşleştirmeli ve sonraki işlemlerin tekrarlanmaması için yinelenen bildirimleri görev kimliğine göre ele almalıdır. Video indirme veya dönüştürme gibi uzun işlemler arka planda çalışabilir. Callback entegrasyonu sırasında sonuçları durum sorgularıyla doğrulamaya devam edebilirsiniz.

İstemler ve sahne örnekleri

Önce özneyi ve eylemi anlatın; ardından kamera hareketi, ortam, ışık ve sesi ekleyin. Referans kullanırken Image 1, Video 1 veya Audio 1 için rol belirtin; aynı medyaya çelişen gereksinimler yüklemeyin.

Aşağıdaki dört İngilizce örnek istem yazımını gösterir; test edilmiş oluşturma sonuçları içermez. İngilizce terimler yeniden kullanımı kolaylaştırır ancak İngilizcenin mutlaka Çinceden daha iyi sonuç verdiği anlamına gelmez. Zamanlama ve görünümü koruma yönergeleri hedefleri belirtir; gerçek çıktıyı kontrol edin.

Ürün reklamı: 8 saniye, referans görsel modu

Ürün görselini input.reference_image_urls dizisinin ilk öğesine koyun, duration: 8 ve aspect_ratio: "16:9" ayarlayın, aşağıdaki metni prompt olarak kullanın. Yukarıdaki referans modu istek yapısını izleyin; referans video gerekmiyorsa reference_video_urls alanını kaldırın.

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.

Önce basit bir çekimle şişe ve etiketin tutarlılığını kontrol edin, ardından daha karmaşık dairesel kamera hareketlerini deneyin.

Karakter diyaloğu: 8 saniye, referans görsel modu

Karakter görselini input.reference_image_urls dizisinin ilk öğesine koyup duration: 8 ve aspect_ratio: "16:9" ayarlayın. Kısa bir replik, dudak senkronizasyonunu, konuşma hızını ve görünümü kontrol etmeyi kolaylaştırır.

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.

Dikey oyun reklamı: 10 saniye, metinden video

duration: 10 ve aspect_ratio: "9:16" ayarlayın. Zaman dilimleri istenen eylem sırasını anlatır; sahne kalabalık görünüyorsa önce eylem ve karakter sayısını azaltın.

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.

Kesintisiz takip çekimi: 10 saniye, metinden video

duration: 10 ve aspect_ratio: "16:9" ayarlayın. Çekimi tek bir özne ve rota etrafında kurun; ardından kesmeleri, özne değişimlerini veya kesintili hareketleri kontrol edin.

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.

Sık sorulan sorular ve entegrasyon sorunları

MiniMax’ın kendi API istek biçimini doğrudan kullanabilir miyim?

Bu örnekler PoYo’nun POST /api/generate/submit ve GET /api/generate/status/{task_id} uç noktalarını kullanır. Adresler, model tanımlayıcıları ve alan yapıları platformlar arasında değişebilir; kullandığınız platformun belgelerini izleyin.

not_started durumunda kalan görevi yeniden göndermeli miyim?

not_started, görevin işlenmeyi beklediğini gösterir; tek başına hata değildir. Görev kimliğini saklayıp sorgulamaya devam edin. Uygulamanızın bekleme sınırına ulaşırsanız görevi kaydedip daha sonra kontrol edin. Gerekirse görev kimliğiyle desteğe başvurun.

Görev kimliği gelmeden gönderim zaman aşımına uğrarsa ne yapmalıyım?

Zaman aşımı, sunucunun görevi kabul etmediğini kanıtlamaz. Önce görev kayıtlarını kontrol edin; gerekirse gönderim zamanı gibi bilgilerle desteğe başvurun. Durum sorgulama uç noktasını kullanmak için görev kimliği gerekir. Başarısız bir sorguyu düzeltmek için görevi yeniden göndermeyin.

Görsel, video ve sesi birlikte referans olarak kullanabilir miyim?

Evet, referans modunda yukarıdaki sayı ve süre sınırları içinde birleştirebilirsiniz. Referans ses için referans görsel veya video gerekir. Bu alanlar başlangıç/bitiş karesi modunun image_urls alanıyla birleştirilemez.

10 saniyelik video ne kadar tutar?

Buradaki fiyatlarla, referans medya olmadan maliyet 10 × 21 = 210 kredi, yani $1.05 olur. Referans videolar ve ilk 5 görselden sonraki referans görseller maliyeti artırır.

Uygulamaya entegre etmeden önce medya URL’lerinin doğrudan indirmeye izin verdiğini doğrulayın, görev kimliklerini kaydedin ve kullanıcı başına uygun oluşturma ve eşzamanlılık sınırları belirleyin. Videoyu yayımlamadan önce karakter görünümünün, ürün şeklinin, metnin, hareketin ve sesin kullanım amacına uygunluğunu kontrol edin.

MiniMax H3 model sayfasında oluşturmayı deneyin veya entegrasyona başlamak için API anahtarı sayfasına gidin. Modeller hakkında daha fazla bilgi için MiniMax H3 incelemesine ve MiniMax H3 ile Seedance 2.5 karşılaştırmasına bakın.