MiniMax Hailuo 2.3 API 整合：用影片介面生成複雜人體運動

目標模型: MiniMax-Hailuo-2.3
推理端點: https://api.toapis.com/v1/videos/generations
相關閱讀: MiniMax H3 API 指南 · H3 運鏡提示詞 · 自動化 R2V 流水線

1. 核心摘要與性能速覽 (TL;DR)

• 任務：在 ToAPIs 的影片生成端點上提交文生影片，或帶首幀的圖生影片，用來製作角色與人體運動鏡頭。
• 約定：MiniMax-Hailuo-2.3 接受整數時長 6 或 10 秒，解析度 768P 或 1080P。1080P 只支援 6 秒。目前 API 參考將提示詞上限寫為 2,000 個字元。
• 模型 ID：文生影片與圖生影片使用目錄字串 MiniMax-Hailuo-2.3。MiniMax-Hailuo-2.3-Fast 僅支援圖生影片，且必須提供首幀 URL。這兩個 ID 都不能與 minimax-h3 互換。
• 運鏡用語：ToAPIs 的 Hailuo 2.3 參考文件列出了 [Push in]、[Pan left, Pedestal up] 這類括號指令。下表是目前文件中的詞彙，硬編碼前請再對一次線上文件。
• 協定：Bearer REST。從提交響應裡取出任務 id，在截止時間內輪詢 GET /v1/videos/generations/{task_id}（或 GET /v1/tasks/{task_id}）。用戶端逾時並不等於上遊任務已經失敗。

2. 複雜人體運動的提示詞寫法

ToAPIs 公開目錄把 MiniMax Hailuo 2.3 描述為面向角色運動、表情與風格的影片模型，適合表現性敘事和角色短片。這是產品定位，不是「肢體絕不變形」的獨立測評。正式上線前，請用清晰的動作語言寫提示詞，並人工覆核取樣。

一條好用的人體運動提示詞，會先寫清身體力學，再寫風格：誰在動、哪條肢體先動、重心如何轉移、動作如何起勢和收勢。對比時長或解析度時，先穩住這一段核心描述，以免把措辭變化誤當成模型差異。

ToAPIs Hailuo 2.3 API 參考將下列運鏡指令寫在提示詞裡，而不是單獨的請求欄位。前端請求約定仍然把 prompt 當作文本校驗。同一對括號裡最多組合 3 條指令表示同時運動，或在句子裡按順序寫出先後運鏡。

圖 1：把靜止姿態當作首幀輸入，在提示詞裡寫隨後的動作，再透過 ToAPIs 閘道提交一次生成請求。

一條方便測試的壓縮模板：

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

示例：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.

圖生影片時，在 image_urls 裡放一個可公開存取的首幀 URL。圖片是起始幀，提示詞描述隨後的運動。目前文件中的圖片限制是：JPG、JPEG、PNG 或 WebP；小於 20 MB；短邊大於 300 px；寬高比介於 2:5 與 5:2 之間。不要在 image_urls 裡傳 base64，本機檔案請先上傳。

MiniMax-Hailuo-2.3-Fast 不接受文生影片，必須提供首幀 URL。Hailuo 2.3 沒有文件化的尾幀欄位；首尾幀過渡屬於 MiniMax-Hailuo-02，不是這個 ID。不要把 H3 的 ratio 或 reference_videos 等欄位直接套到 Hailuo 2.3 請求上。

Playground 選項可能會顯示小寫的 768p / 1080p，目前 API 示例使用 768P 和 1080P。批量自動化前，先確認你的帳戶實際接受哪一種寫法。把同樣的運鏡措辭拿到 MiniMax H3 上也可以作為提示詞文本，但時長、解析度和媒體模式約定不同，換 ID 前請重讀那篇指南。

3. 生產級實作：cURL 與 Python

步驟 1：用 cURL 提交

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

步驟 2：Python 輔助函式與輪詢

官方文件目前寫的是公開源站 https://toapis.com（中國大陸請使用 https://toapis.cn）。本系列其他指南使用 https://api.toapis.com。選定一個基址並保持一致。下面的示例遵循文件中的任務查詢路徑以及 completed / failed 狀態；上線前請對照你帳戶的 API 參考，確認 id、result.data[0].url 和回應包絡。

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

把提示詞模板版本和任務記錄放在一起，這樣才能分清是模型變了還是措辭變了。若要做首幀任務，給 dispatch_motion_clip 傳入 image_url=。Fast SKU 必須提供該參數。

Hailuo 2.3 的基礎時長是 6 或 10 秒。不要把 1080P 和 duration: 10 一起發送。若你需要連續的 4–15 秒時長、參考媒體或尾幀輸入，那是另一套約定，請看 H3 API 指南 和 R2V 流水線教程。

4. 錯誤處理與狀態碼對照

下表只是排查起點，並不保證與 ToAPIs 的精確錯誤碼一一對應。HTTP 查詢成功後，仍然要讀取任務 status。

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

5. 定價與 FinOps ROI

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

• 不要沿用策劃稿裡的單價。 按秒或按條計費、計費單位，以及對失敗任務的處理，都會隨模型、解析度、時長、線路和帳戶變化。ToAPIs 定價頁上的官方廠商參考行僅供展示，未必等於你帳戶的實際扣費。預測鏡頭成本前，請查閱目前目錄和你的帳戶報價。
• Fast 是另一個 SKU，不是同一 ID 上的免費加速開關。文件寫明 MiniMax-Hailuo-2.3-Fast 僅支援圖生影片，請單獨確認它的帳戶價格。
• 把花費控制在提示詞層：先用 768P 和 6 秒打樣，保留帶版本的模板，一次只改一個變量；用戶端逾時後，先查任務狀態再決定是否重提。
• 廠商直籤合同常帶年框、席位和預付門檻。ToAPIs 計費通常是按量付費，請以帳戶目前條款為準。

6. 常見問題

結構化問答見文章 frontmatter 中的 FAQ。摘要：請求裡的模型字串是 MiniMax-Hailuo-2.3，不是連字號形式的頁面 slug，也不是 H3 的 ID；1080P 僅支援 6 秒；Fast 必須提供首幀 URL，且不支援文生影片；文件中的運鏡指令寫在提示詞裡，不是獨立欄位；Hailuo 2.3 沒有尾幀輸入。

7. 行動清單

• 在 ToAPIs 開發者入口 建立金鑰。
• 用 MiniMax-Hailuo-2.3、resolution: "768P" 和 6 秒時長連通測試上面的 cURL。
• 確認帳戶接受的是 768P 還是 768p，並對 GET /v1/videos/generations/{id} 做有截止時間的輪詢。
• 接下來：若需要另一套時長或媒體約定，閱讀 H3 運鏡指南；並在 Hailuo 2.3 模型指南 查看目前目錄狀態。