Guida all’API MiniMax H3: integrazione con PoYo, prezzi e prompt

Con l’API MiniMax H3 di PoYo puoi generare video 2K di 5–15 secondi da testo, fotogrammi iniziali e finali o contenuti di riferimento. Senza riferimenti, un video di 5 secondi ha un costo stimato di 105 crediti ($0.525).

La guida parte dalla prima richiesta e prosegue con prezzi, modalità di input, esempi Python e Node.js e prompt per scene diverse. Tutti gli endpoint e i prezzi indicati si riferiscono a PoYo.

Avvio rapido: invia un’attività e recupera il video

1. Invia un’attività video di 5 secondi

Ottieni una chiave API dalla console PoYo, sostituisci YOUR_POYO_API_KEY ed esegui il comando in un terminale o sul server. Conserva la chiave lato server; non inserirla nel codice del browser o in repository pubblici.

Nelle richieste a PoYo, il valore di model per MiniMax H3 è hailuo-03. L’esempio seguente invia un’attività di generazione a pagamento.

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

Dopo l’invio riuscito, leggi l’ID dell’attività da data.task_id. Questo esempio mostra la struttura della risposta con un ID segnaposto:

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

2. Consulta il risultato dell’attività

Assegna a TASK_ID l’ID restituito e usa la stessa chiave API:

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

Un invio riuscito significa che l’attività è stata accettata; devi ancora attendere il completamento della generazione. Il campo data.status nella risposta di consultazione può assumere quattro valori:

Ecco un esempio di risposta a generazione completata. URL e data sono illustrativi:

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

Per le definizioni dei campi e gli esempi degli altri stati, consulta la documentazione PoYo sulla consultazione delle attività. Se una richiesta di stato fallisce temporaneamente o scade il tempo di attesa, conserva l’ID e riprova più tardi; non inviare automaticamente un’altra generazione a pagamento.

Come viene fatturato MiniMax H3 su PoYo

I prezzi seguenti sono stati verificati il 21 settembre 2026. Tutti gli importi sono in USD, con 1 credito = $0.005. Prima di generare in grandi quantità, verifica i prezzi aggiornati nella pagina del modello.

Crediti stimati = 21 × (secondi in output + secondi fatturabili del video di riferimento) + 6.4 × numero di immagini di riferimento oltre le 5. Con 5 immagini o meno, il costo aggiuntivo delle immagini è 0. Moltiplica i crediti stimati per $0.005 per ottenere il costo in USD. Per video di riferimento con frazioni di secondo, viene usata la durata determinata dal server.

L’ultimo esempio usa 21 × (10 + 5) + 6.4 × (7 − 5). Si tratta di costi per singola generazione; se una ripresa richiede più tentativi, considera ogni generazione nel budget.

Scegliere modalità di input e riferimenti

I campi multimediali inviati determinano la modalità di input. L’esempio di avvio rapido usa testo in video. Aggiungi i campi appropriati quando vuoi specificare fotogrammi iniziali e finali o utilizzare riferimenti.

Non combinare image_urls con alcun campo reference_*_urls. Tutti gli URL dei contenuti devono essere accessibili pubblicamente e consentire il download diretto.

Limiti di parametri e contenuti

I limiti seguenti provengono dalla documentazione dell’API MiniMax H3 di PoYo:

• prompt è obbligatorio e accetta fino a 2000 caratteri.
• duration è un intero di 5–15 secondi, con valore predefinito 5; resolution supporta solo 2K.
• Testo in video supporta 21:9, 16:9, 4:3, 1:1, 3:4 e 9:16, con 16:9 come valore predefinito. La modalità riferimento supporta anche adaptive e lo usa come predefinito.
• Puoi fornire fino a 9 immagini, 3 video e 3 clip audio di riferimento. Ogni video o clip audio deve durare 2–15 secondi; la durata totale dei video e quella degli audio non devono superare, separatamente, 15 secondi.

Esempio di richiesta con fotogrammi iniziale e finale

Usa il JSON seguente come corpo di POST /api/generate/submit. Gli URL su example.com sono segnaposto: sostituiscili con contenuti scaricabili di tua proprietà prima dell’invio. Per usare solo un fotogramma iniziale, elimina il secondo URL dall’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"
    ]
  }
}

Esempio con riferimenti immagine e video combinati

Usa Image 1 per l’aspetto del personaggio e Video 1 per il movimento della camera desiderato. Corrispondono rispettivamente al primo elemento dell’array di immagini e di quello di video. Sostituisci gli URL e verifica la durata del video di riferimento prima dell’invio.

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

Esempi di integrazione con Python e Node.js

Gli esempi separano invio e consultazione in due funzioni: prima ottieni e salva l’ID, poi attendi il risultato. Se la consultazione si interrompe, puoi riprenderla con l’ID originale senza generare di nuovo. Solo le richieste di stato vengono ritentate in caso di errori di connessione, timeout, HTTP 429 e alcuni errori 5xx; gli invii non vengono ritentati automaticamente.

Entrambe le implementazioni attendono 10 secondi tra le consultazioni, effettuano al massimo 60 consultazioni e impostano un timeout di 30 secondi per richiesta. L’attesa totale include quindi anche la durata delle richieste. Sono impostazioni degli esempi, non una garanzia sui tempi di generazione. Adatta intervalli e criteri di ripetizione alle esigenze dell’applicazione.

Python: inviare un’attività e controllare il risultato

Installa la dipendenza con python -m pip install requests e imposta la variabile d’ambiente POYO_API_KEY come descritto sopra. Questo script Python sincrono esegue il polling di un’attività di generazione asincrona.

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

Per riprendere la consultazione, chiama direttamente wait_for_h3(saved_task_id). Errori HTTP come 401 e 403, errori dell’API o risposte inattese interrompono il polling; risolvine la causa prima di continuare.

Node.js: usare fetch integrato

Il JavaScript seguente utilizza fetch, integrato in Node.js 20 o versioni successive, senza dipendenze per un client HTTP. Salvalo in un file .mjs ed eseguilo sul 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));

Per riprendere la consultazione, sostituisci le chiamate di invio e consultazione in fondo al file con waitForH3(savedTaskId). Questo esempio è adatto a script o attività in background. In un’applicazione web, restituisci l’ID al frontend e monitora la generazione in background, senza lasciare in attesa una richiesta di pagina.

Ricevere risultati tramite webhook

Puoi anche passare callback_url al livello principale della richiesta, accanto a model e input, ad esempio https://your-domain.com/webhooks/poyo. PoYo invia il risultato a quell’URL quando l’attività riesce o fallisce.

Il ricevitore deve confrontare l’ID con i record locali e gestire le notifiche duplicate in base all’ID per evitare di ripetere le operazioni successive. Download e transcodifica del video possono essere eseguiti in background. Durante l’integrazione dei callback puoi continuare a usare le richieste di stato per verificare i risultati.

Prompt ed esempi di scene

Descrivi prima soggetto e azione, poi aggiungi movimento della camera, ambientazione, luce e suono. Quando usi riferimenti, specifica il ruolo di Image 1, Video 1 o Audio 1, evitando requisiti contraddittori per lo stesso contenuto.

I quattro esempi in inglese mostrano come scrivere i prompt; non includono risultati di generazione verificati. I termini inglesi ne facilitano il riutilizzo, ma non implicano che l’inglese funzioni necessariamente meglio del cinese. Tempi e istruzioni per conservare l’aspetto sono obiettivi: controlla il risultato effettivo.

Pubblicità di prodotto: 8 secondi, modalità immagine di riferimento

Inserisci l’immagine del prodotto come primo elemento di input.reference_image_urls, imposta duration: 8 e aspect_ratio: "16:9" e usa il testo seguente come prompt. Segui la struttura di richiesta della modalità riferimento mostrata sopra; elimina reference_video_urls se non serve un video di riferimento.

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.

Inizia con una ripresa semplice per verificare la coerenza di flacone ed etichetta, poi prova movimenti orbitali più complessi.

Dialogo di un personaggio: 8 secondi, modalità immagine di riferimento

Inserisci l’immagine del personaggio come primo elemento di input.reference_image_urls e imposta duration: 8 e aspect_ratio: "16:9". Una battuta breve facilita il controllo della sincronizzazione labiale, della velocità del parlato e dell’aspetto.

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.

Pubblicità verticale di un gioco: 10 secondi, testo in video

Imposta duration: 10 e aspect_ratio: "9:16". I segmenti temporali esprimono l’ordine desiderato delle azioni; se la scena è troppo affollata, riduci prima il numero di azioni e personaggi.

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.

Ripresa continua in movimento: 10 secondi, testo in video

Imposta duration: 10 e aspect_ratio: "16:9". Organizza la ripresa attorno a un soggetto e un percorso, poi verifica la presenza di tagli, cambiamenti del soggetto o movimenti discontinui.

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.

Domande frequenti e risoluzione dei problemi

Posso usare direttamente il formato di richiesta dell’API di MiniMax?

Questi esempi usano POST /api/generate/submit e GET /api/generate/status/{task_id} di PoYo. Endpoint, identificatori dei modelli e strutture dei campi possono variare tra piattaforme; segui la documentazione di quella che utilizzi.

Devo reinviare un’attività che rimane in not_started?

not_started indica che l’attività è in attesa di elaborazione, non un errore di per sé. Conserva l’ID e continua a consultare lo stato. Se viene raggiunto il limite di attesa dell’applicazione, registra l’attività e controllala più tardi. Se necessario, contatta l’assistenza indicando l’ID.

Cosa faccio se l’invio va in timeout prima di ricevere l’ID?

Un timeout non dimostra che il server non abbia accettato l’attività. Controlla prima i record; se necessario, contatta l’assistenza indicando dettagli come l’ora di invio. Per consultare lo stato serve l’ID dell’attività. Non usare il reinvio per rimediare a una consultazione fallita.

Posso combinare immagini, video e audio come riferimenti?

Sì, nella modalità riferimento e nei limiti di quantità e durata indicati. L’audio di riferimento richiede un’immagine o un video di riferimento. Questi campi non possono essere combinati con image_urls della modalità fotogrammi iniziale e finale.

Quanto costa un video di 10 secondi?

Ai prezzi indicati, senza riferimenti, il costo è di 10 × 21 = 210 crediti, cioè $1.05. I video di riferimento e le immagini oltre le prime 5 aumentano il costo.

Prima dell’integrazione, verifica che gli URL consentano download diretti, salva gli ID delle attività e imposta limiti adeguati di generazione e concorrenza per utente. Prima di pubblicare un video, controlla che aspetto dei personaggi, forma dei prodotti, testo, movimento e suono siano adatti all’uso previsto.

Prova la generazione nella pagina del modello MiniMax H3 oppure visita la pagina delle chiavi API per iniziare l’integrazione. Per approfondire, leggi la recensione di MiniMax H3 e il confronto tra MiniMax H3 e Seedance 2.5.