MiniMax H3 API (Hailuo 03): runnable cURL and Node.js examples

Call MiniMax H3, exposed as model ID hailuo-03, for 2K text-to-video and reference-driven video generation.

Answer: To use the MiniMax H3 API (Hailuo 03), send a server-side request to POST https://api.poyo.ai/api/generate/submit with model hailuo-03 and a PoYo API key. The examples in this repository are runnable with Node.js 22+ or cURL.

Last verified against the live PoYo schema and pricing on August 9, 2026.

Quickstart

1. Create a key in the PoYo dashboard.
2. Copy .env.example to .env and replace the placeholder.
3. Run node node/index.mjs.

POYO_API_KEY=YOUR_POYO_API_KEY_HERE
POYO_BASE_URL=https://api.poyo.ai

The complete cURL request is in curl/generate.md. The Node.js example submits the task and polls until finished or failed.

Model IDs

• hailuo-03

Use the exact IDs above. Product names and API model IDs are not always identical.

Request fields

Field	Requirement	Meaning
prompt	required	Video description, up to 2,000 characters.
duration	required	Integer from 5 to 15 seconds.
resolution	required	2K.
aspect_ratio	optional	adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, or 9:16.
image_urls	optional	One or two first/last-frame images.
reference_image_urls	optional	Up to 9 reference images.
reference_video_urls	optional	Up to 3 clips; each 2-5 seconds and at most 15 seconds total.
reference_audio_urls	optional	Up to 3 clips; each 2-5 seconds.

Pricing snapshot

Usage	Price
Output without reference video	$0.105 per output second
Output with reference video	$0.105 per billed second
Reference images 1-5	Free
Each reference image after 5	$0.032

Pricing can change. Confirm the current amount on the model page before a production rollout.

Best for

• 2K cinematic clips
• first-and-last-frame motion
• multi-reference character shots

Important behavior

• Use the API model ID hailuo-03 even though the product name is MiniMax H3.
• First/last-frame image mode cannot be mixed with reference inputs.
• When reference video is used, billed duration includes output plus reference-video duration.
• Reference audio requires at least one reference image or video.

Async production flow

submit -> persist data.task_id -> poll during development -> receive callback_url webhook in production

Treat finished and failed as terminal states. Accept a webhook only for task IDs your system created, process it idempotently, and reconcile the final state through the status endpoint.

Repository map

• curl/generate.md — copy-paste request
• node/index.mjs — dependency-free Node.js example
• docs/production-notes.md — limits and rollout checklist

Links

• Try MiniMax H3 API (Hailuo 03) on PoYo
• API reference
• All PoYo examples
• PoYo model catalog

License

MIT