MiniMax Hailuo 2.3 API Integration: Generating Complex Human Motion in AI Video

Target Model: MiniMax-Hailuo-2.3
Inference Endpoint: https://api.toapis.com/v1/videos/generations
Related: MiniMax H3 API Guide · H3 camera-movement prompts · Automated R2V pipeline

1. TL;DR & Performance Overview

• Job: Submit text-to-video or first-frame image-to-video jobs for character and human-motion clips on the ToAPIs generations endpoint.
• Contract: MiniMax-Hailuo-2.3 accepts integer durations of 6 or 10 seconds and resolutions 768P or 1080P. 1080P supports 6 seconds only. The current API reference caps the prompt at 2,000 characters.
• IDs: Use the catalog string MiniMax-Hailuo-2.3 (text-to-video and image-to-video). MiniMax-Hailuo-2.3-Fast is image-to-video only and requires a first-frame URL. Neither ID is interchangeable with minimax-h3.
• Camera language: The ToAPIs Hailuo 2.3 reference documents bracketed directives such as [Push in] and [Pan left, Pedestal up]. Treat the table below as the current documented vocabulary, then confirm it against the live docs before you hard-code a shot grammar.
• Protocol: Bearer REST. Persist the task id from the submission envelope and poll GET /v1/videos/generations/{task_id} (or GET /v1/tasks/{task_id}) with a bounded deadline. A client timeout is not proof that the upstream task failed.

2. Human-Motion Prompt Patterns

The public ToAPIs catalog describes MiniMax Hailuo 2.3 as a video model for character motion, expressions, and style in expressive stories and character clips. That is product positioning, not an independent benchmark of "zero limb warping." For production work, write prompts that describe one subject and one primary action in clear mechanical language, then review the take.

A useful human-motion prompt names the body mechanics before it adds style: who is moving, which limb leads, how weight shifts, and how the action starts and finishes. Keep that core stable when you A/B duration or resolution; otherwise a wording change can explain a different take.

The ToAPIs Hailuo 2.3 API reference documents the camera directives below. They live in the prompt string, not in a separate request field. The frontend request contract still validates prompt as text. Combine at most three directives in one bracket for simultaneous movement, or sequence them in the sentence for ordered moves.

Figure 1: Treat a still pose as the first-frame input, describe the subsequent action in the prompt, and submit one generation request through the ToAPIs gateway.

A compact template that stays testable:

SUBJECT and PRIMARY ACTION (lead limb, weight shift, follow-through), ENVIRONMENT, [CAMERA], STYLE NOTES

Example: A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs.

For image-to-video, send one publicly reachable first-frame URL in image_urls. The image is the starting frame; the prompt describes the motion that follows. Current documented image limits are JPG, JPEG, PNG, or WebP; under 20 MB; short side greater than 300 px; and an aspect ratio between 2:5 and 5:2. Do not put base64 in image_urls — upload a local file first.

MiniMax-Hailuo-2.3-Fast does not accept text-to-video: a first-frame URL is required. Hailuo 2.3 does not document a last-frame field; first-to-last-frame interpolation belongs to MiniMax-Hailuo-02, not this ID. Do not copy H3 fields such as ratio or reference_videos onto a Hailuo 2.3 request.

Playground option labels may show lowercase 768p / 1080p. Current API examples use 768P and 1080P. Confirm the value your account accepts before you automate a batch. The same camera wording can be reused when you move a shot to MiniMax H3, but the duration, resolution, and media-mode contracts are different — switch IDs only after you reread that guide.

3. Production Implementation: cURL & Python

Step 1: cURL dispatch

curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs",
    "duration": 6,
    "resolution": "768P"
  }'

Step 2: Python helper and poller

Official docs currently document the public origin https://toapis.com (and https://toapis.cn for mainland China). Other ToAPIs guides in this series use https://api.toapis.com. Pick one base URL and keep it consistent. The snippet below follows the documented task-status path and the completed / failed statuses; confirm id, result.data[0].url, and the envelope against the API reference for your account before you ship.

import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def dispatch_motion_clip(
    prompt: str,
    duration: int = 6,
    resolution: str = "768P",
    image_url: str | None = None,
    model: str = "MiniMax-Hailuo-2.3",
) -> str:
    if resolution == "1080P" and duration != 6:
        raise ValueError("1080P currently supports a 6-second duration only")
    payload = {
        "model": model,
        "prompt": prompt,
        "duration": duration,
        "resolution": resolution,
        "metadata": {"prompt_optimizer": True, "aigc_watermark": False},
    }
    if image_url:
        payload["image_urls"] = [image_url]
    elif model == "MiniMax-Hailuo-2.3-Fast":
        raise ValueError("MiniMax-Hailuo-2.3-Fast requires a first-frame image_urls value")
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("id") or data.get("task_id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_task(task_id: str, deadline_s: int = 300) -> str:
    poll_url = f"{BASE}/v1/videos/generations/{task_id}"
    interval = 5.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        if poll.status_code == 429:
            retry_after = poll.headers.get("Retry-After")
            time.sleep(float(retry_after) if retry_after else min(interval * 2, 30))
            continue
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status == "completed":
            return data["result"]["data"][0]["url"]
        if status == "failed":
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 10.0)
    raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")


if __name__ == "__main__":
    prompt = (
        "A contemporary dancer in a black practice leotard plants the left foot, "
        "then uncoils a slow 360-degree turn with the right arm leading and the "
        "torso stacked over the standing leg, warehouse skylight, [Tracking shot], "
        "photorealistic, no morphing limbs"
    )
    task_id = dispatch_motion_clip(prompt)
    print("Task:", task_id)
    print("Video:", poll_task(task_id))

Store the prompt template version next to the task record so you can tell a model change from a wording change. If you need a first-frame job, pass image_url= into dispatch_motion_clip. For the Fast SKU, that argument is required.

Base Hailuo 2.3 duration is 6 or 10 seconds. Do not send 1080P with duration: 10. If you need continuous 4–15 second clips, reference media, or last-frame inputs, that is a different contract — see the H3 API guide and the R2V pipeline tutorial.

4. Error Handling & Status Matrix

The categories below are diagnostic starting points, not a guarantee of exact ToAPIs error codes. A successful HTTP query still requires you to read task status.

$\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)$

5. Pricing & FinOps ROI

$\text{Estimated cost} = \text{successful billable jobs} \times \text{current account rate for that model, duration, and resolution}$

• Do not reuse planning-draft unit prices. Per-second or per-video rates, billing units, and failed-task treatment vary by model, resolution, duration, route, and account. Official vendor reference rows on the ToAPIs pricing page are display-only and may not match what your account is billed. Read the current catalog and your account quote before you forecast a shot list.
• Fast is a different SKU, not a free speed switch on the same ID. MiniMax-Hailuo-2.3-Fast is documented as image-to-video only. Confirm its current account price separately.
• Control spend in the prompt layer: draft at 768P and 6 seconds, keep a versioned template, change one variable at a time, and do not resubmit after a client timeout until you have checked task status.
• Official vendor contracts often add annual commitments, seat quotas, and prepayment floors. ToAPIs billing is typically pay-as-you-go — confirm the active terms on your account.

6. Frequently Asked Questions

See the FAQ block in frontmatter. Summary: the request model string is MiniMax-Hailuo-2.3, not a hyphenated slug and not an H3 ID; 1080P is limited to 6 seconds; Fast requires a first-frame URL and does not support text-to-video; documented camera directives live in the prompt, not as separate fields; Hailuo 2.3 has no last-frame input.

7. Action Checklist

• Create a key on the ToAPIs Developer Portal.
• Smoke-test the cURL snippet with MiniMax-Hailuo-2.3, resolution: "768P", and a 6-second duration.
• Confirm whether your account expects 768P or 768p, and poll GET /v1/videos/generations/{id} with a bounded deadline.
• Next: the H3 camera-movement guide if you need a different duration or media contract, and the Hailuo 2.3 model guide for live catalog status.