API-guide til MiniMax H3: PoYo-integration, priser og prompts

Med PoYos MiniMax H3-API kan du generere 2K-videoer på 5–15 sekunder ud fra tekst, første og sidste billedramme eller referencemedier. Uden referencemedier er prisen for en video på 5 sekunder anslået til 105 kreditter ($0.525).

Denne guide begynder med din første anmodning og gennemgår derefter priser, inputtilstande, eksempler i Python og Node.js samt prompts til forskellige scener. Alle endpoints og priser i guiden gælder for PoYo.

Hurtig start: send en opgave, og hent videoen

1. Send en opgave om en video på 5 sekunder

Hent en API-nøgle i PoYo-konsollen, erstat YOUR_POYO_API_KEY nedenfor, og kør kommandoen i en terminal eller på din server. Opbevar nøglen på serveren; tag den ikke med i kode, der kører i browseren, eller i offentlige repositories.

I PoYo-anmodninger er model-værdien for MiniMax H3 hailuo-03. Det følgende eksempel sender en betalt genereringsopgave.

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

Efter en vellykket indsendelse kan du læse opgave-ID'et i data.task_id. Dette eksempel viser svarets struktur med et pladsholder-ID:

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

2. Forespørg opgavens resultat

Sæt TASK_ID til det returnerede opgave-ID, og brug den samme API-nøgle:

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 indsendelse betyder, at opgaven er accepteret; du skal stadig vente på, at videogenereringen bliver færdig. Svaret på forespørgslen har fire mulige værdier for data.status:

Her er et eksempel på et fuldført svar. URL'en og tidsstemplet er illustrative:

{
  "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 dokumentation til forespørgsler om opgaver for feltdefinitioner og svareksempler for andre tilstande. Hvis en forespørgsel midlertidigt fejler, eller din ventetid udløber, så gem opgave-ID'et, og forespørg igen senere; send ikke automatisk en ny betalt generering.

Sådan fungerer prissætningen for MiniMax H3 på PoYo

Følgende priser blev kontrolleret den 21. september 2026. Alle beløb er i USD med 1 kredit = $0.005. Før du genererer i store mængder, så bekræft de seneste priser på modelsiden.

Anslåede kreditter = 21 × (outputsekunder + fakturerbare sekunder af referencevideo) + 6,4 × antallet af referencebilleder ud over 5. Med 5 eller færre referencebilleder er tillægget for ekstra billeder 0. Gang de anslåede kreditter med $0.005 for at få prisen i USD. For referencevideoer med brøkdele af sekunder bruger faktureringen den varighed, som serveren har målt.

Det sidste eksempel bruger 21 × (10 + 5) + 6.4 × (7 − 5). Det er priser pr. generering; hvis en optagelse kræver flere forsøg, skal du medregne hver generering i dit budget.

Vælg en inputtilstand og referencemedier

De mediefelter, du sender, afgør inputtilstanden. Eksemplet i hurtigstarten ovenfor bruger tekst-til-video. Tilføj de relevante felter, når du vil angive start- og slutrammer eller bruge referencemedier.

Kombinér ikke image_urls med noget reference_*_urls-felt. Alle medie-URL'er skal være offentligt tilgængelige og kunne downloades direkte.

Grænser for parametre og medier

Følgende grænser stammer fra dokumentationen til PoYos MiniMax H3-API:

• prompt er påkrævet og accepterer op til 2000 tegn.
• duration er et heltal fra 5–15 sekunder med 5 som standard; resolution understøtter kun 2K.
• Tekst-til-video understøtter 21:9, 16:9, 4:3, 1:1, 3:4 og 9:16 med 16:9 som standard. Referencetilstand understøtter også adaptive og bruger det som standard.
• Du kan angive op til 9 referencebilleder, 3 referencevideoer og 3 referencelydklip. Hver video eller hvert lydklip skal vare 2–15 sekunder; den samlede videovarighed og den samlede lydvarighed skal hver især holde sig inden for 15 sekunder.

Eksempel på anmodning med første/sidste billedramme

Brug JSON'en nedenfor som body i POST /api/generate/submit. Medie-URL'er under example.com er pladsholdere: erstat dem med dine egne medier, der kan downloades, før du sender. Hvis du kun vil bruge en startramme, så fjern den anden URL fra arrayet.

{
  "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 kombineret billed- og videoreference

Brug Image 1 til at angive karakterens udseende og Video 1 til den ønskede kamerabevægelse. De henviser henholdsvis til det første element i billedarrayet og i videoarrayet. Erstat medie-URL'erne, og kontrollér referencevideoens varighed, før du sender.

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

Integrationseksempler i Python og Node.js

Eksemplerne nedenfor deler indsendelse og forespørgsel op i to funktioner: hent og gem først opgave-ID'et, og vent derefter på resultatet. Hvis forespørgslen afbrydes, kan du genoptage med det oprindelige opgave-ID uden at generere igen. Kun statusforespørgsler forsøger igen ved forbindelsesfejl, timeouts, HTTP 429 og udvalgte 5xx-fejl; indsendelser forsøges ikke automatisk igen.

Begge implementeringer venter 10 sekunder mellem forespørgslerne, foretager op til 60 forespørgsler og sætter en timeout på 30 sekunder pr. anmodning. Den samlede ventetid omfatter derfor også anmodningernes varighed. Det er programindstillinger til eksemplerne og ikke en garanti for genereringstiden. Tilpas intervallerne og strategien for nye forsøg til din applikations behov.

Python: send en opgave, og poll efter resultatet

Installér afhængigheden med python -m pip install requests, og sæt miljøvariablen POYO_API_KEY som beskrevet ovenfor. Dette synkrone Python-script poller en asynkron genereringsopgave.

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 at genoptage forespørgslen kalder du direkte wait_for_h3(saved_task_id). HTTP-fejl som 401 og 403, fejl på API-niveau eller uventede svar stopper pollingen; afhjælp årsagen, før du fortsætter.

Node.js: brug den indbyggede fetch

Det følgende JavaScript bruger den indbyggede fetch i Node.js 20 eller nyere, så der ikke er brug for nogen afhængighed til en HTTP-klient. Gem det som en .mjs-fil, og kø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 at genoptage forespørgslen skal du erstatte kaldene til indsendelse og forespørgsel i slutningen af filen med waitForH3(savedTaskId). Dette pollingeksempel egner sig til scripts eller baggrundsopgaver. I en webapplikation bør du returnere opgave-ID'et til frontend og følge genereringen i baggrunden i stedet for at lade en sideanmodning vente.

Modtag resultater via en webhook

Du kan også angive callback_url på øverste niveau i indsendelsesanmodningen, ved siden af model og input, for eksempel https://your-domain.com/webhooks/poyo. PoYo sender resultatet til den URL, når opgaven lykkes eller mislykkes.

Modtageren bør matche opgave-ID'et med lokale registreringer og håndtere dublerede notifikationer ud fra opgave-ID'et, så efterfølgende handlinger ikke gentages. Tidskrævende arbejde som at downloade eller omkode videoen kan køre som baggrundsopgaver. Du kan stadig bruge statusforespørgsler til at verificere resultater, mens du integrerer callbacks.

Prompts og eksempler på scener

Beskriv først subjektet og handlingen, og tilføj derefter kamerabevægelse, omgivelser, belysning og lyd. Når du bruger referencemedier, så angiv rollen for Image 1, Video 1 eller Audio 1, så en enkelt reference ikke bærer modstridende krav.

De fire engelske eksempler nedenfor illustrerer, hvordan man skriver prompts; de indeholder ikke testede genereringsresultater. Engelske udtryk gør eksemplerne lette at genbruge, men det betyder ikke nødvendigvis, at engelsk virker bedre end kinesisk. Instruktioner om timing og bevarelse af udseende beskriver tilsigtede resultater; kontrollér det faktiske output.

Produktreklame: 8 sekunder, referencebilledtilstand

Læg produktbilledet først i input.reference_image_urls, sæt duration: 8 og aspect_ratio: "16:9", og brug teksten nedenfor som prompt. Følg strukturen for anmodninger i referencetilstand ovenfor; fjern reference_video_urls, hvis du ikke har brug for en referencevideo.

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 en simpel optagelse for at se, om flasken og etiketten forbliver konsistente, og prøv derefter en mere kompleks kamerabevægelse i kredsløb.

Karakterdialog: 8 sekunder, referencebilledtilstand

Læg karakterbilledet først i input.reference_image_urls, og sæt duration: 8 og aspect_ratio: "16:9". En kort replik gør det lettere at kontrollere læbesynkronisering, talehastighed og karakterens udseende.

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.

Vertikal spilreklame: 10 sekunder, tekst-til-video

Sæt duration: 10 og aspect_ratio: "9:16". Tidssegmenterne udtrykker den tilsigtede rækkefølge af handlinger; hvis scenen føles overfyldt, så begynd med at skære ned på antallet af handlinger og karakterer.

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.

Sammenhængende tracking shot: 10 sekunder, tekst-til-video

Sæt duration: 10 og aspect_ratio: "16:9". Byg optagelsen op omkring ét subjekt og én rute, og kontrollér derefter for klip, ændringer i subjektet eller usammenhængende bevægelse.

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.

Ofte stillede spørgsmål og fejlfinding af integrationen

Kan jeg bruge MiniMax' eget anmodningsformat direkte?

Disse eksempler bruger PoYos POST /api/generate/submit og GET /api/generate/status/{task_id}. Endpoints, model-ID'er og feltstrukturer kan variere mellem platforme; følg dokumentationen for den platform, du bruger.

Skal jeg sende en opgave igen, hvis den bliver stående på not_started?

not_started betyder, at opgaven venter på at blive behandlet; det er ikke i sig selv en fejl. Gem opgave-ID'et, og fortsæt med at forespørge. Hvis din applikations ventegrænse udløber, så registrér opgaven, og tjek den senere. Kontakt om nødvendigt support med opgave-ID'et.

Hvad hvis indsendelsen får timeout, før jeg modtager et opgave-ID?

En timeout på anmodningen beviser ikke, at serveren ikke har accepteret opgaven. Tjek først opgaveregistreringerne; kontakt om nødvendigt support med oplysninger som tidspunktet for indsendelsen. Du skal bruge et opgave-ID for at kunne bruge endpointet til statusforespørgsler. Betragt ikke ny indsendelse som en løsning på en mislykket forespørgsel.

Kan jeg kombinere billeder, video og lyd som referencer?

Ja, kombinér dem i referencetilstand inden for grænserne for antal og varighed ovenfor. Referencelyd kræver et referencebillede eller en referencevideo. Disse felter kan ikke kombineres med image_urls til tilstanden med første/sidste billedramme.

Hvor meget koster en video på 10 sekunder?

Til de priser, der er angivet her, og uden referencemedier er prisen 10 × 21 = 210 kreditter, eller $1.05. Referencevideoer og referencebilleder ud over de første 5 lægger sig oveni prisen.

Før du integrerer i din applikation, så bekræft, at medie-URL'er tillader direkte download, gem opgave-ID'er, og sæt passende grænser for generering og samtidighed pr. bruger. Før du udgiver en genereret video, så kontrollér, at karakterens udseende, produktets form, tekst, bevægelse og lyd passer til den tilsigtede brug.

Prøv at generere på MiniMax H3-modelsiden, eller besøg siden med API-nøgler for at begynde at integrere. Læs mere om modellerne i anmeldelsen af MiniMax H3 og sammenligningen af MiniMax H3 og Seedance 2.5.