--- title: "Hailuo 02 JSON Prompt — MiniMax Video Newcomer Guide" description: "Beginner-friendly Hailuo 02 JSON prompt guide: every field explained, 3 copy-paste examples, and when to use it vs alternatives. 17 credits on AI Content Drop." canonical: "https://aicontentdrop.com/blog/hailuo-2-3-json-prompt-guide" source: "https://aicontentdrop.com/blog/hailuo-2-3-json-prompt-guide" --- ## What This Guide Does This guide explains every field in a Hailuo 02 (version 2.3) JSON prompt — the structured text request you send to MiniMax's Hailuo video API to turn a written description into a smooth, cinematic video clip. By the end you'll be able to send your first Hailuo 02 request and understand every field in the JSON, even if you have never called an AI model API before. We'll start with what Hailuo 02 actually is and what it's best at, then show you a complete copy-pasteable request body. From there we'll break down every field one by one — data type, required vs optional, allowed values, and a plain-English "good vs bad" example for each. We'll close with three ready-to-run prompt bodies, the `curl` and JavaScript snippets you need to actually submit a request, common error fixes, a decision table comparing Hailuo 02 to its closest alternatives, and a cost breakdown so you know exactly what to budget. No prior coding or AI experience needed. ## What Is Hailuo 02 (2.3)? Hailuo 02 is a text-to-video model developed by MiniMax, a Chinese AI lab. You give it a written description and it generates a fluid video clip — no source images, no storyboard, just words in, video out. MiniMax built the Hailuo family specifically for**smooth, physics-aware motion**: objects move with natural inertia, fabric ripples believably, liquids flow without the jitter that plagues cheaper models. Version 2.3 (marketed as "Hailuo 02") is the headline entry in this family — it targets the value-budget tier, delivering cinematic-quality motion at a lower credit cost than premium competitors. It excels at lifestyle B-roll, product reveals, and any scene where flowing, continuous movement is more important than ultra-high resolution. The one thing Hailuo 02 does not do is generate audio — it outputs silent video. If you need native speech or ambient sound in a single generation call, a model with built-in audio is a better fit. For a broader look at what is available across all AI video models, see our [best AI video generators for 2026](https://aicontentdrop.com/blog/best-ai-video-generators-2026) roundup. Hailuo 02 is accessible via MiniMax's official Hailuo API (the video generation endpoint at `api.minimax.io`). On AI Content Drop, each Hailuo 02 generation costs **17 credits** — billed only after your video generates successfully (post-deduct billing). A failed or cancelled generation does not charge you anything. Seventeen credits makes Hailuo 02 one of the most affordable cinematic video models on the platform: you get smooth physics-aware motion at a fraction of what premium models charge. For a head-to-head price and quality comparison across the top models, check our [Kling vs Veo vs Sora benchmark](https://aicontentdrop.com/blog/kling-veo-sora-benchmark) — it puts Hailuo in context against the full competitive landscape. ## The Complete JSON Prompt Below is a full Hailuo 02 API request body you can copy, paste, and send right now. This is **JSON** — JavaScript Object Notation, a plain-text format that APIs use to receive structured instructions. Each line is a key–value pair separated by a colon; together they tell Hailuo 02 exactly what video to create. ``` { "model": "MiniMax-Hailuo-02", "prompt": "A sleek matte-black wireless speaker on a dark marble surface, rotating slowly clockwise, warm studio rim lighting from the left, ultra-clean dark background, cinematic shallow depth of field, 4K photorealistic", "duration": 6, "resolution": "1080p", "aspect_ratio": "16:9" } ``` At a glance: `model` selects the Hailuo 02 checkpoint; `prompt` is your text description of the scene; `duration` controls how many seconds of video to generate; `resolution` sets output quality; and `aspect_ratio` determines the frame shape — landscape, portrait, or square. Each of these is explained in full below. Consult the latest MiniMax Hailuo API documentation for any additional optional fields not shown here. ## Field-by-Field Breakdown Let's go through every field in the canonical request above. For each one you'll see its data type, whether it is required, what the default is when you leave it out, the allowed values or range, and a plain-English "good vs bad" example so you know exactly how each setting affects your output. ### model **Type:** string (enum) | **Required:** yes Tells the MiniMax Hailuo API which model checkpoint to run. For Hailuo 02 use `"MiniMax-Hailuo-02"`. The model string is case-sensitive — a lowercase or abbreviated version will cause the API to reject your request. Pinning an explicit model string also means a future API update won't silently redirect your requests to a different checkpoint, which protects your production prompts from unexpected output changes. **Good:** `"MiniMax-Hailuo-02"` — exact, explicit, reproducible. **Bad:** `"hailuo"` — too vague; the API will return an "InvalidModel" error. ### prompt **Type:** string | **Required:** yes | **Max length:** ~2,000 characters (confirm in the latest MiniMax Hailuo docs) This is the main description of the scene you want to generate. Think of it as a detailed instruction to a cinematographer: describe the subject, its action, the camera angle, lighting, and visual style in a single paragraph. Hailuo 02 responds especially well to motion-descriptive language — words like "rotating slowly," "drifting through," and "pulled gently" activate the model's physics-aware motion engine. A single clear movement per clip consistently outperforms a prompt that chains several unrelated actions together. **Good:** `"A glass perfume bottle on a white marble surface, slow 360-degree rotation, warm rim lighting from the right, soft bokeh background, cinematic"` **Bad:** `"bottle flies then explodes then logo appears"` — multiple disconnected events in one clip produce incoherent motion. ### duration **Type:** number (integer) | **Required:** no | **Default:** 6 | **Allowed values:** 6 (confirm additional durations in the latest MiniMax Hailuo docs) Controls how many seconds of video to generate. **Duration** is the length of the finished clip in seconds. Based on publicly available MiniMax documentation as of early 2026, Hailuo 02 currently supports a 6-second output. Check the latest MiniMax Hailuo API reference for any updates to the duration range, as MiniMax has expanded supported durations across previous Hailuo versions. **Good:** `6` — confirmed supported duration for a polished, unhurried product reveal. **Bad:** `30` — exceeds the model's current maximum; the API will return a validation error. ### resolution **Type:** string (enum) | **Required:** no | **Default:** `"1080p"` Sets the output resolution. **Resolution** describes how many pixels tall the video is — more pixels means a sharper, more detailed image, but also a longer generation time. `"1080p"` (full HD, 1920 × 1080 in landscape) is the standard choice for most ad placements. Confirm available resolution options in the latest MiniMax Hailuo API docs, as MiniMax may offer additional tiers. **Good:** `"1080p"` — sharp enough for all major ad platforms, generates faster than higher resolutions. **Bad:** `"4K"` — if this is not a confirmed enum value, the API will reject it. Write "4K" in your *prompt text* to signal quality intent; use the resolution field for the supported enum string. ### aspect_ratio **Type:** string (enum) | **Required:** no | **Default:** `"16:9"` Sets the width-to-height relationship of the video frame. **Aspect ratio** determines how the video looks and where it fits on social platforms. `"16:9"` is landscape (YouTube, desktop), `"9:16"` is vertical (TikTok, Instagram Reels, Shorts), and `"1:1"` is square (Instagram feed, some Meta placements). You cannot request a custom ratio — pick from the supported list and crop afterward if needed. **Good:** `"9:16"` for a TikTok ad — vertical fills the entire phone screen and maximizes engagement. **Bad:** `"4:5"` — if not a supported enum, the API returns a validation error. Crop a 1:1 output to 4:5 in your video editor instead. ## Allowed Values Reference Table Bookmark this table. It covers every confirmed enum value and range for Hailuo 02 as of May 2026. If a value you try is not in this table, the API will return a 400 validation error. Always cross-check against the latest MiniMax Hailuo API documentation, as MiniMax regularly expands available options across model updates. | Field | Allowed Values | Notes | | --- | --- | --- | | model | `MiniMax-Hailuo-02` | Case-sensitive. Exact string required. | | duration | `6` (seconds) | Confirm additional durations in the latest MiniMax docs. | | resolution | `1080p` (Full HD) `720p` (HD — confirm availability) | Default 1080p. Confirm full list in latest MiniMax Hailuo docs. | | aspect_ratio | `16:9` (landscape) `9:16` (vertical/portrait) `1:1` (square) | Default 16:9. Cannot request custom ratios. | | prompt | Any string up to ~2,000 characters | More detail improves physics-aware motion coherence. | ## 3 Working Copy-Paste Examples Below are three complete, ready-to-run JSON request bodies for three different use cases. Each one is valid JSON you can drop into a `curl` command or fetch call immediately. ### Example 1 — E-Commerce Product Shot A rotating wireless speaker on a clean studio surface. Swap the subject and lighting language for any physical product — sneakers, skincare bottles, supplements, tech gear. The 1:1 ratio targets Instagram feed placements and Meta carousel ads. Hailuo 02's physics-aware motion engine handles the continuous rotation without the stuttering or "flip" artifacts that cheaper models produce at the 180-degree mark. Expect a polished, unhurried product reveal with consistent studio lighting across all 6 seconds. ``` { "model": "MiniMax-Hailuo-02", "prompt": "A premium matte-black wireless speaker on a minimalist white pedestal, rotating slowly clockwise 360 degrees, soft directional studio lighting with a subtle amber rim highlight on the right edge, ultra-clean white background, photorealistic 4K, cinematic shallow depth of field", "duration": 6, "resolution": "1080p", "aspect_ratio": "1:1" } ``` The 1:1 aspect ratio fills the Instagram square feed natively, so you avoid letterboxing. Mentioning "4K" in the prompt text signals visual quality intent to the model even when the resolution field is capped at 1080p. Six seconds is enough for a full, unhurried 360-degree rotation that reads as premium rather than rushed. ### Example 2 — Portrait / Character (Founder-to-Camera) A confident person speaking directly to camera — the standard format for founder testimonials, UGC ads, and service-business promos. Use 9:16 vertical for TikTok and Instagram Reels. The subtle dolly-in camera move creates the feeling of a professional shoot even with a minimal setup. Note: Hailuo 02 does not generate speech or lip-sync — this is a silent clip. Pair it with a voice-over track in post-production or use the UGC Factory on AI Content Drop for a lip-synced version. ``` { "model": "MiniMax-Hailuo-02", "prompt": "A confident woman in her early 30s wearing a tailored cobalt blazer, standing in a sunlit modern co-working space, looking directly into the camera with a calm, assured expression, slow subtle dolly-in from medium shot to medium close-up, warm soft-box lighting, shallow depth of field, cinematic color grading", "duration": 6, "resolution": "1080p", "aspect_ratio": "9:16" } ``` The 9:16 vertical ratio fills the entire phone screen on TikTok and Instagram Reels — no black bars, maximum visual impact. Hailuo 02's smooth motion physics keep facial movement natural across the dolly-in, which is one of the most demanding motion tests for a budget video model. Six seconds gives enough runway for the move to feel intentional without overstaying its welcome. ### Example 3 — Cinematic Scene (Moody Street Shot) An atmospheric B-roll clip for lifestyle brands, agency reels, or travel content. Hailuo 02 excels at flowing environmental motion — rain reflections, crowd movement, ambient light flicker — and this prompt is designed to extract that strength. The 16:9 landscape ratio suits YouTube pre-rolls and widescreen social placements. At 17 credits per generation, you can run multiple iterations to find the perfect atmospheric take without breaking your budget. ``` { "model": "MiniMax-Hailuo-02", "prompt": "A rain-slicked city street at night, neon signs reflected in wet asphalt, people with umbrellas drifting past glowing shopfronts in slow motion, a lone figure in a dark coat pauses and looks up at the falling rain, moody cinematic color grade with deep teal and warm amber tones, slow tracking shot at street level", "duration": 6, "resolution": "1080p", "aspect_ratio": "16:9" } ``` Atmospheric scenes with flowing liquids and ambient crowd movement are where Hailuo 02 most visibly outperforms models in the same price bracket. The physics-aware motion engine handles the rain reflections and umbrella movement as a coherent physical system rather than independent moving patches. At 17 credits you can run this prompt five or six times to explore variation before committing to a final take. ## How to Send the Request An **API endpoint** is a web address your code sends data to — think of it like a specific door on a building that only accepts deliveries of a particular format. For Hailuo 02, the official door is MiniMax's Hailuo API. The exact endpoint path and authentication details are documented at [platform.minimax.io](https://platform.minimax.io) — consult the latest provider docs for the current URL structure, as MiniMax occasionally updates versioned path prefixes. You send your JSON request body to that address with your API key in the header, and the service returns a task ID you can poll until the video is ready. ### curl (command line) `curl` is a command-line tool that lets you send HTTP requests directly from your terminal. The snippet below follows the standard MiniMax pattern — replace `YOUR_MINIMAX_API_KEY` with your actual key and confirm the exact endpoint path in the latest MiniMax Hailuo API reference: ``` curl -X POST \ https://api.minimax.io/v1/video_generation \ -H "Authorization: Bearer YOUR_MINIMAX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "MiniMax-Hailuo-02", "prompt": "A sleek matte-black wireless speaker on a dark marble surface, rotating slowly clockwise, warm studio rim lighting from the left, ultra-clean dark background, cinematic shallow depth of field, 4K photorealistic", "duration": 6, "resolution": "1080p", "aspect_ratio": "16:9" }' # Note: confirm the exact endpoint path in the latest MiniMax Hailuo API docs. ``` Hailuo 02 generation is asynchronous — the API immediately returns a task ID rather than waiting for the video to finish. You then poll a status endpoint with that task ID until the video URL is ready. The next section shows exactly what both responses look like. ### JavaScript fetch If you're building a web app or Node.js script, the `fetch` API sends the same request without needing a terminal. Replace `YOUR_MINIMAX_API_KEY` with your actual key: ``` // Confirm the exact endpoint path in the latest MiniMax Hailuo API docs. const response = await fetch( 'https://api.minimax.io/v1/video_generation', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_MINIMAX_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ model: 'MiniMax-Hailuo-02', prompt: 'A sleek matte-black wireless speaker on a dark marble surface, rotating slowly clockwise, warm studio rim lighting from the left, ultra-clean dark background, cinematic shallow depth of field, 4K photorealistic', duration: 6, resolution: '1080p', aspect_ratio: '16:9', }), } ); const data = await response.json(); console.log(data.task_id); // Use this ID to poll for your video ``` Or skip the API key entirely — paste your prompt into [/chat](https://aicontentdrop.com/) or [/generate/video](https://aicontentdrop.com/best-ai-video-generator) on AI Content Drop and we'll handle the request for you. No API key, no polling code, no infrastructure to manage — your video appears in your dashboard when it's ready. ## What the Response Looks Like Hailuo 02 generation is **asynchronous** — the API does not wait for the video to finish before sending a response. Instead, it immediately returns a **task ID**. A task ID is a unique reference string (think of it like a package tracking number) that you use to check whether your video is ready. Here is what the initial response looks like: ``` { "task_id": "hailuo_task_abc123def456", "status": "queued" } ``` Once you have the `task_id`, you call the status endpoint repeatedly every few seconds — this is called **polling**. You keep checking until the `status` field changes from `"queued"` or `"processing"` to `"completed"`. A completed response looks like this: ``` { "task_id": "hailuo_task_abc123def456", "status": "completed", "video_url": "https://cdn.minimax.io/results/your-video.mp4", "duration": 6, "resolution": "1080p", "aspect_ratio": "16:9" } ``` `video_url` is the download link for your finished video. It is a temporary signed URL — download the file promptly because it will expire. The `status` field cycles through `queued → processing → completed` (or `failed` if something went wrong). Poll every 5–10 seconds; most Hailuo 02 generations complete in 60–120 seconds. Consult the latest MiniMax Hailuo API docs for the exact polling endpoint path and any changes to the response schema. ## Common Errors and Fixes - Error: "InvalidModel: model not found" — The model string is misspelled, wrong case, or refers to a version that is not available on your account tier. Double-check the exact string MiniMax-Hailuo-02 (capital M, capital H, capital zero-two) against the latest MiniMax model catalog. - Error: 401 Unauthorized — Your API key is missing, expired, or pasted with extra whitespace. Check that the Authorization header reads Bearer YOUR_MINIMAX_API_KEY with no leading or trailing spaces. Regenerate the key in your MiniMax console if you're unsure. - Error: "InvalidParameter: aspect_ratio" — The aspect_ratio value you supplied is not in the supported list. Use one of: 16:9 , 9:16 , 1:1 . If you need a different ratio, generate the closest option and crop in your video editor. - Error: "InvalidParameter: duration out of range" — The duration value you set is not supported. Set it to 6 (the confirmed Hailuo 02 duration) and re-submit. Check the latest MiniMax docs if you believe additional durations have been released. - Error: "Content policy violation" — Your prompt triggered a content-safety filter. Remove any references to violence, explicit content, or real individuals by name. Rephrase in neutral, descriptive language — for example, "a figure in a dark coat" rather than a named person. - Error: "Quota exceeded" — You've hit your MiniMax account's daily or monthly API quota. Wait for the quota window to reset or top up your MiniMax balance. On AI Content Drop, quota management is handled automatically by the platform. - task_id status stuck on "queued" for over 5 minutes — MiniMax video generation queues can back up during peak hours. Wait another few minutes. If the status stays queued beyond 10 minutes, submit a new request — the original task may have silently timed out on the server side. ## Hailuo 02 vs Alternatives — When to Use This Every model has a sweet spot. Here's a practical decision table so you pick the right tool for each job. You can browse and compare all available models on the [AI Content Drop marketplace](https://aicontentdrop.com/marketplace). | Use Hailuo 02 if… | Use Kling 3.0 if… | Use Seedance 2.0 if… | | --- | --- | --- | | You want smooth, physics-aware motion at the lowest credit cost (17 credits) — lifestyle B-roll, product reveals, atmospheric scenes | You need precise camera trajectory control or image-to-video with a reference photo (22 credits) | You need native audio, speech, or lip-sync generated in the same call (56 credits) | | Your scene involves flowing physical elements — rain, fabric, liquids, crowd movement — where coherent motion physics matter most | You're building product ads where a specific dolly or pan trajectory is essential to the creative | You want a talking-head UGC clip with lip-synced voiceover in a single generation pass | | Budget is your top priority — at 17 credits you get cinematic-quality motion for less than any audio-capable model on the platform | You need a longer clip (Kling 3.0 supports durations beyond 6 seconds on some settings) | You're willing to spend 3× the credits for a fully self-contained video with synchronized sound | For a deeper look at how Hailuo 02 compares to Kling and Sora on standardized prompts, the [Kling vs Veo vs Sora benchmark](https://aicontentdrop.com/blog/kling-veo-sora-benchmark) includes Hailuo in its quality scoring. And if you want to calculate the exact cost of a multi-model production run before you commit credits, the [video ad cost calculator](https://aicontentdrop.com/blog/video-ad-cost-calculator-ai-models) walks through the math for every model on the platform. ## Cost Math for Newcomers Let's make the numbers concrete. Hailuo 02 costs **17 credits per generation** on AI Content Drop (post-deduct — you are only charged on a successful generation). Say you want to produce 10 ad variants of the same product shot to A/B test different camera angles and motion speeds: **10 ad variants × 17 credits = 170 credits** The Starter plan gives you 150 credits per month for $19. That means 10 Hailuo 02 generations slightly exceeds one Starter month (170 credits vs 150 available) — but just barely. The Professional plan gives you 450 credits per month for $49, comfortably covering 26 Hailuo 02 generations with room left for other work. If you want to run aggressive creative testing — say 50 variants across multiple products — the Ultra plan (1,000 credits for $99/month) fits all 850 credits with a large buffer for chat, images, and other model work. Hailuo 02 at 17 credits is one of the few video models where you can run double-digit test batches on the Starter plan. To see how Hailuo 02's 17-credit price stacks up against every other model in one place, the [video ad cost calculator](https://aicontentdrop.com/blog/video-ad-cost-calculator-ai-models) shows you exact credit counts and dollar equivalents for any batch size. ## Glossary **Prompt** The text description you write to tell the model what to generate. Think of it as a detailed instruction note to a cinematographer. **JSON (JavaScript Object Notation)** A plain-text format used to send structured data to APIs. It looks like key–value pairs wrapped in curly braces: `{"key": "value"}`. **API request** A message your app or script sends to a web service, asking it to do something — in this case, generate a video. The API processes the request and sends a response back. **Endpoint** A specific URL that an API listens to for incoming requests. Different endpoints perform different actions — for example, submitting a video generation job versus checking its status. **Task ID** A unique identifier returned immediately when you submit a video generation job. You use it to track your job's progress and retrieve the finished video URL. **Polling** Periodically checking a task status endpoint (e.g., every 5 seconds) to find out whether your asynchronous job has finished. You stop polling when the status is `completed` or `failed`. **Aspect ratio** The width-to-height relationship of the video frame. 16:9 is landscape (widescreen), 9:16 is vertical (phone-friendly), 1:1 is square. Hailuo 02 accepts these as colon- separated strings: `16:9`, `9:16`, `1:1`. **Physics-aware motion** A capability of some video models to simulate how real objects move — inertia, fluid dynamics, cloth physics — rather than just interpolating pixels between frames. Hailuo 02's physics engine is its headline differentiator at the budget tier. **Post-deduct billing** A billing model where credits are only charged after a successful generation. If the generation fails or is cancelled, no credits are deducted. ## FAQ ### Can I just use the chat instead of writing JSON? Yes. Head to [/chat](https://aicontentdrop.com/) on AI Content Drop, describe what you want in plain English, and the platform routes your request to the Hailuo endpoint (or whichever model best fits your brief) without you writing a single line of JSON. The JSON guide here is useful if you want fine-grained control or are building your own integration directly against the MiniMax Hailuo API. ### What if I get a 401 error? A 401 means the API rejected your credentials. The most likely causes are: the API key is missing from the `Authorization` header, the key was copied with extra whitespace, or the key has expired. Regenerate the key in your MiniMax console and re-paste it carefully. On AI Content Drop you never manage API keys directly — authentication is handled for you. ### How do I get an aspect ratio that isn't in the list? You can't request a custom pixel dimension — you must pick from the supported `aspect_ratio` values listed in the reference table. If your target placement needs a ratio not on the list (for example, 4:5 for some Meta feed placements), generate the closest available size and crop in your video editor afterward. Cropping a 1:1 output to 4:5 removes only a small strip from the top and bottom, rarely affecting the main subject. ### Does Hailuo 02 support audio generation? No. Hailuo 02 is a silent text-to-video model — it generates video only, with no embedded audio track. If you need native speech, ambient sound, or lip-synced audio in the same generation call, look at Seedance 2.0 (56 credits, full multimodal audio with lip-sync) or pair a Hailuo 02 clip with a separate voice-over track in post-production using the UGC Factory on AI Content Drop.