MiniMax H3 API-guide: integrasjon med PoYo, priser og prompter

Med PoYos MiniMax H3 API kan du generere 2K-videoer på 5–15 sekunder fra tekst, første og siste bilderute eller referansemedier. Uten referansemedier har en video på 5 sekunder en anslått kostnad på 105 kreditter ($0.525).

Denne guiden starter med den første forespørselen din og tar deretter for seg priser, inputmoduser, eksempler i Python og Node.js samt prompter for ulike scener. Alle endepunkter og priser i guiden gjelder PoYo.

Hurtigstart: send inn en oppgave og hent videoen

1. Send inn en videooppgave på 5 sekunder

Hent en API-nøkkel fra PoYo-konsollen, erstatt YOUR_POYO_API_KEY nedenfor, og kjør kommandoen i en terminal eller på serveren din. Hold nøkkelen på serveren; ikke ta den med i nettleserkode eller offentlige repositorier.

I PoYo-forespørsler er model-verdien for MiniMax H3 hailuo-03. Eksemplet nedenfor sender inn en betalt genereringsoppgave.

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

Etter en vellykket innsending leser du oppgave-ID-en fra data.task_id. Dette eksemplet viser strukturen i svaret med en plassholder for oppgave-ID:

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

2. Hent resultatet av oppgaven

Sett TASK_ID til oppgave-ID-en du fikk tilbake, og bruk den samme API-nøkkelen:

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

En vellykket innsending betyr at oppgaven er tatt imot; du må fortsatt vente på at videogenereringen blir ferdig. Svaret på spørringen har fire mulige verdier for data.status:

Her er et eksempel på et fullført svar. URL-en og tidsstempelet er bare til illustrasjon:

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

Se PoYos dokumentasjon for oppgavespørringer for feltdefinisjoner og eksempler på svar for andre tilstander. Hvis en spørring feiler midlertidig eller ventetiden din løper ut, tar du vare på oppgave-ID-en og spør igjen senere; ikke send automatisk inn en ny betalt generering.

Slik fungerer prisene for MiniMax H3 på PoYo

Prisene nedenfor ble sjekket 21. september 2026. Alle beløp er i USD, med 1 kreditt = $0.005. Før du genererer i store mengder, bør du bekrefte de nyeste prisene på modellsiden.

Anslåtte kreditter = 21 × (sekunder output + fakturerbare sekunder referansevideo) + 6,4 × antall referansebilder utover 5. Med 5 eller færre referansebilder er tillegget for bilder 0. Gang de anslåtte kredittene med $0.005 for å få kostnaden i USD. For referansevideoer med brøkdeler av sekunder brukes varigheten som serveren fastsetter.

Det siste eksemplet bruker 21 × (10 + 5) + 6.4 × (7 − 5). Dette er kostnader per generering; hvis et klipp krever flere forsøk, må du ta med hver generering i budsjettet.

Velg inputmodus og referansemedier

Mediefeltene du sender inn, avgjør inputmodusen. Hurtigstarteksemplet ovenfor bruker tekst-til-video. Legg til de aktuelle feltene når du trenger å angi start- og sluttramme eller bruke referansemedier.

Ikke kombiner image_urls med noen av reference_*_urls-feltene. Alle medie-URL-er må være offentlig tilgjengelige og kunne lastes ned direkte.

Grenser for parametere og medier

Grensene nedenfor er hentet fra PoYos API-dokumentasjon for MiniMax H3:

• prompt er påkrevd og tar opptil 2000 tegn.
• duration er et heltall fra 5–15 sekunder, med 5 som standard; resolution støtter bare 2K.
• Tekst-til-video støtter 21:9, 16:9, 4:3, 1:1, 3:4 og 9:16, med 16:9 som standard. Referansemodus støtter i tillegg adaptive og bruker det som standard.
• Du kan oppgi opptil 9 referansebilder, 3 referansevideoer og 3 referanselydklipp. Hvert video- eller lydklipp må være 2–15 sekunder; samlet videovarighet og samlet lydvarighet må hver for seg holde seg innenfor 15 sekunder.

Eksempel på forespørsel med første/siste bilderute

Bruk JSON-en nedenfor som body i POST /api/generate/submit. Medie-URL-er under example.com er plassholdere: erstatt dem med dine egne nedlastbare medier før du sender inn. Hvis du bare vil bruke en startramme, fjerner du den andre URL-en fra arrayen.

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

Eksempel med kombinert bilde- og videoreferanse

Bruk Image 1 til å angi figurens utseende og Video 1 for ønsket kamerabevegelse. Disse viser til det første elementet i henholdsvis bilde-arrayen og video-arrayen. Erstatt medie-URL-ene og sjekk varigheten på referansevideoen før du sender inn.

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

Integrasjonseksempler i Python og Node.js

Eksemplene nedenfor deler innsending og spørring i to funksjoner: hent og lagre oppgave-ID-en først, og vent deretter på resultatet. Hvis spørringen blir avbrutt, fortsetter du med den opprinnelige oppgave-ID-en uten å generere på nytt. Bare statusspørringer prøver på nytt ved tilkoblingsfeil, tidsavbrudd, HTTP 429 og utvalgte 5xx-feil; innsendinger prøves ikke automatisk på nytt.

Begge implementasjonene venter 10 sekunder mellom spørringene, gjør opptil 60 spørringer og setter et tidsavbrudd på 30 sekunder per forespørsel. Den totale ventetiden inkluderer derfor også tiden forespørslene tar. Dette er programinnstillinger for eksemplene, ikke en garanti for genereringstid. Tilpass intervallene og strategien for nye forsøk etter behovene i applikasjonen din.

Python: send inn en oppgave og poll etter resultatet

Installer avhengigheten med python -m pip install requests og sett miljøvariabelen POYO_API_KEY som beskrevet ovenfor. Dette synkrone Python-skriptet poller en asynkron genereringsoppgave.

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

For å fortsette spørringen kaller du wait_for_h3(saved_task_id) direkte. HTTP-feil som 401 og 403, feil på API-nivå eller uventede svar stopper pollingen; rett opp årsaken før du fortsetter.

Node.js: bruk den innebygde fetch

JavaScript-koden nedenfor bruker den innebygde fetch i Node.js 20 eller nyere, så du trenger ingen avhengighet til en HTTP-klient. Lagre den som en .mjs-fil og kjør den på serveren.

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

For å fortsette spørringen erstatter du innsendings- og spørrekallene på slutten av filen med waitForH3(savedTaskId). Dette polling-eksemplet passer for skript eller bakgrunnsoppgaver. I en nettapplikasjon bør du returnere oppgave-ID-en til frontend og følge genereringen i bakgrunnen i stedet for å la en sideforespørsel stå og vente.

Motta resultater via webhook

Du kan også sende med callback_url på toppnivå i innsendingsforespørselen, ved siden av model og input, for eksempel https://your-domain.com/webhooks/poyo. PoYo sender resultatet til denne URL-en når oppgaven lykkes eller mislykkes.

Mottakeren bør matche oppgave-ID-en mot lokale poster og håndtere dupliserte varsler etter oppgave-ID for å unngå at operasjoner lenger ned i kjeden gjentas. Tidkrevende arbeid som nedlasting eller omkoding av videoen kan kjøres i bakgrunnsoppgaver. Du kan fortsatt bruke statusspørringer til å kontrollere resultatene mens du integrerer callbacks.

Prompter og sceneeksempler

Beskriv motivet og handlingen først, og legg deretter til kamerabevegelse, omgivelser, lys og lyd. Når du bruker referansemedier, angir du rollen til Image 1, Video 1 eller Audio 1, slik at én enkelt referanse ikke får motstridende krav.

De fire engelske eksemplene nedenfor illustrerer hvordan du skriver prompter; de inneholder ikke testede genereringsresultater. Engelske begreper gjør eksemplene lette å gjenbruke, men betyr ikke at engelsk nødvendigvis fungerer bedre enn kinesisk. Instruksjoner om timing og bevaring av utseende beskriver tiltenkte resultater; kontroller det faktiske resultatet.

Produktreklame: 8 sekunder, referansebildemodus

Legg produktbildet først i input.reference_image_urls, sett duration: 8 og aspect_ratio: "16:9", og bruk teksten nedenfor som prompt. Følg strukturen for forespørsler i referansemodus ovenfor; fjern reference_video_urls hvis du ikke trenger en referansevideo.

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.

Start med et enkelt bilde for å sjekke om flasken og etiketten holder seg konsekvente, og prøv deretter mer komplekse kamerabevegelser i bue rundt produktet.

Dialog med figur: 8 sekunder, referansebildemodus

Legg bildet av figuren først i input.reference_image_urls og sett duration: 8 og aspect_ratio: "16:9". En kort replikk gjør det lettere å sjekke leppesynk, taletempo og figurens utseende.

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.

Stående spillreklame: 10 sekunder, tekst-til-video

Sett duration: 10 og aspect_ratio: "9:16". Tidssegmentene uttrykker ønsket rekkefølge på handlingene; hvis scenen virker overfylt, begynner du med å redusere antall handlinger og figurer.

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.

Sammenhengende sporingsbilde: 10 sekunder, tekst-til-video

Sett duration: 10 og aspect_ratio: "16:9". Bygg opp bildet rundt ett motiv og én rute, og sjekk deretter om det finnes klipp, endringer i motivet eller brudd i bevegelsen.

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.

Vanlige spørsmål og feilsøking av integrasjonen

Kan jeg bruke MiniMax' eget forespørselsformat direkte?

Disse eksemplene bruker PoYos POST /api/generate/submit og GET /api/generate/status/{task_id}. Endepunkter, modellidentifikatorer og feltstrukturer kan variere mellom plattformer; følg dokumentasjonen for plattformen du bruker.

Bør jeg sende inn på nytt en oppgave som blir stående i not_started?

not_started betyr at oppgaven venter på behandling; det er ikke i seg selv en feil. Ta vare på oppgave-ID-en og fortsett å spørre. Hvis applikasjonens ventegrense løper ut, registrerer du oppgaven og sjekker den senere. Kontakt support med oppgave-ID-en ved behov.

Hva om innsendingen får tidsavbrudd før jeg får en oppgave-ID?

Et tidsavbrudd på forespørselen beviser ikke at serveren ikke tok imot oppgaven. Sjekk oppgaveoversikten først; kontakt eventuelt support med opplysninger som tidspunktet for innsendingen. Du trenger en oppgave-ID for å bruke endepunktet for statusspørringer. Ikke se på ny innsending som en løsning på en mislykket spørring.

Kan jeg kombinere bilder, video og lyd som referanser?

Ja, kombiner dem i referansemodus innenfor grensene for antall og varighet ovenfor. Referanselyd krever et referansebilde eller en referansevideo. Disse feltene kan ikke kombineres med image_urls for modus med første/siste bilderute.

Hva koster en video på 10 sekunder?

Med prisene som er oppgitt her, uten referansemedier, er kostnaden 10 × 21 = 210 kreditter, eller $1.05. Referansevideoer og referansebilder utover de første 5 øker kostnaden.

Før du integrerer i applikasjonen din, bør du bekrefte at medie-URL-ene tillater direkte nedlasting, lagre oppgave-ID-er og sette passende grenser for generering og samtidighet per bruker. Før du publiserer en generert video, bør du sjekke at figurenes utseende, produktets form, tekst, bevegelse og lyd passer til det tiltenkte formålet.

Prøv å generere på modellsiden for MiniMax H3, eller gå til siden for API-nøkler for å starte integrasjonen. Les mer om modellene i anmeldelsen av MiniMax H3 og sammenligningen av MiniMax H3 og Seedance 2.5.