MiniMax H3 提示詞指南：如何用 API 寫出電影級運鏡

目標模型: minimax-h3
推理端點: https://api.toapis.com/v1/videos/generations
相關閱讀: MiniMax H3 API 指南 · H3 與 Turbo 如何選擇 · 自動化 R2V 流水線

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

目標：把分鏡表寫成可重用的 MiniMax H3 提示詞——主體、動作、運鏡路徑、鏡頭與燈光——再提交到 ToAPIs 的 generations 端點。
寫法：先寫運鏡意圖，再寫主體。把方向性短語與焦距（例如 35mm 與 85mm）以及燈光提示組合在一起。
約定：基礎 minimax-h3 接受整數 4–15 秒 成片。使用 ratio（16:9、9:16 以及下文列出的其他比值）。這是前端請求約定，不是時延或畫質基準測試。
語法提醒：括號標籤只是提示詞助手。除非上游模型文檔明確說明，否則不要把 [Pan Left] 當成已記錄的原生命令。
協議：Bearer REST。只提交一次，持久化任務標識，並在有截止時間的前提下輪詢文檔中的任務狀態端點。

2. 運鏡提示詞模式

一條有效的 H3 提示詞會先描述 一個場景和一個主動作，再補充運鏡、鏡頭或風格。對比模型或時長時保持這些部分穩定，否則措辭變化本身就可能造成不同結果。

下表中的標籤是 提示詞助手，不是有保證的命令語法。ToAPIs 前端約定把提示詞當作文本校驗（最長 7,000 個 Unicode 字元），並不能證明 [Pan Left] 這類字串是 H3 的原生命令。把它們當作模板裡的統一詞彙，再檢查成片。

提示詞助手	視覺軌跡	典型用途
`[Pan Left]` / `[Pan Right]`	固定機位水平旋轉	風景揭示、天際線橫掃
`[Tilt Up]` / `[Tilt Down]`	固定機位垂直俯仰	高樓、高大主體、天空揭示
`[Dolly In]` / `[Dolly Out]`	鏡頭靠近或遠離主體	加強情緒張力
`[Truck Left]` / `[Truck Right]`	橫向跟蹤移動	與車輛或行人並行
`[Crane Shot]` / `[Pedestal Up]`	機位垂直升高	高角度建立鏡頭
`[Orbit 180]` / `[Arc Shot]`	繞主體半圓運動	產品展示、角色揭示
`[Hitchcock Zoom]`	推進同時拉遠（或相反）	心理衝擊、突然頓悟

主體節點周圍的抽象運鏡軌跡

圖 1：把橫搖、俯仰、推軌和環繞理解為圍繞同一主體的提示詞軌跡，再通過 ToAPIs 閘道提交一次生成請求。

可重用、便於對照的緊湊模板：

text

[CAMERA] SUBJECT and ACTION, LIGHTING, shot on LENS, STYLE NOTES

示例：[Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur.

在首幀（R2V）任務中，同樣的提示詞用於描述鏡頭如何圍繞或離開錨點圖像。請求欄位見 R2V 流水線教程。幀輸入與參考媒體仍是互斥模式。

目前前端支援的 ratio 值為 adaptive、21:9、16:9、4:3、1:1、3:4 和 9:16。存在幀輸入時會強制為 adaptive。不要發送 aspect_ratio，約定欄位名是 ratio。

3. 生產級實作：cURL 與 Python

步驟 1：cURL 提交

bash

curl -X POST "https://api.toapis.com/v1/videos/generations" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "[Orbit 180 + Slow Dolly In] Matte black mechanical wristwatch resting on volcanic stone, moody low-key rim lighting, subtle steam haze, shot on 85mm macro lens, photorealistic, cinematic motion blur",
    "duration": 6,
    "ratio": "16:9"
  }'

步驟 2：Python 提示詞助手與輪詢

請將欄位名和回應結構與你帳戶對應的 API 參考對齊。下面的示例使用了其他 ToAPIs 影片指南中的任務狀態路徑；上線前請確認 task_id、status 和 video_url 是否符合該結構。

python

import os
import time
import requests

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


def build_cinematic_prompt(
    subject: str,
    camera_move: str,
    lighting: str,
    lens: str = "35mm anamorphic",
) -> str:
    return (
        f"[{camera_move}] {subject}, {lighting}, "
        f"shot on {lens}, photorealistic, cinematic motion blur."
    )


def dispatch_camera_shot(prompt: str, duration: int = 6, ratio: str = "16:9") -> str:
    payload = {
        "model": "minimax-h3",
        "prompt": prompt,
        "duration": duration,
        "ratio": ratio,
    }
    res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
    res.raise_for_status()
    data = res.json()
    task_id = data.get("task_id") or data.get("id")
    if not task_id:
        raise RuntimeError(f"Unexpected submission envelope: {data}")
    return task_id


def poll_task(task_id: str, deadline_s: int = 180) -> str:
    poll_url = f"https://api.toapis.com/v1/videos/tasks/{task_id}"
    interval = 3.0
    start = time.time()
    while time.time() - start < deadline_s:
        time.sleep(interval)
        poll = requests.get(poll_url, headers=HEADERS, timeout=15)
        poll.raise_for_status()
        data = poll.json()
        status = data.get("status")
        if status in {"succeeded", "success"}:
            return data["video_url"]
        if status in {"failed", "error"}:
            raise RuntimeError(f"Generation failed: {data.get('error')}")
        interval = min(interval * 1.5, 8.0)
    raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")


if __name__ == "__main__":
    prompt = build_cinematic_prompt(
        subject="Matte black mechanical wristwatch resting on volcanic stone",
        camera_move="Orbit 180 + Slow Dolly In",
        lighting="Moody low-key rim lighting, subtle steam haze",
        lens="85mm macro lens",
    )
    task_id = dispatch_camera_shot(prompt)
    print("Task:", task_id)
    print("Video:", poll_task(task_id))

把提示詞模板版本和任務記錄放在一起，才能區分模型變化和措辭變化。客戶端超時並不等於上游任務失敗——再次提交計費任務前，先查詢狀態。

基礎 H3 時長為 4 到 15 秒的整數。Max 家族 ID 從 5 秒起，並有各自的解析度列表；Turbo 不接受參考媒體。切換 ID 前請先閱讀 API 指南。

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

下表中的分類只是排查起點，並不保證與 ToAPIs 的精確錯誤碼一一對應。

HTTP 狀態碼	常見分類	建議操作
`400`	欄位無效、取值不受支援，或媒體模式衝突	檢查模型 ID、時長、`ratio`、解析度，並確認幀輸入未與參考媒體混用
`401`	API Key 缺失或無效	在 ToAPIs 控制台輪換密鑰，並核對 `Authorization` 頭
`429`	速率或並發限制	帶抖動退避，確認安全後再重試
`5xx` 或網路超時	閘道或上游暫時異常	重新提交前先查任務狀態，並使用有上限的重試策略

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

5. 定價與 FinOps ROI

$\text{Estimated cost} = \text{successful output seconds} \times \text{current account rate per second}$

不要沿用規劃稿中的單價。 每秒費率、計費單位以及對失敗任務的處理會因模型、路由和帳戶而異。預估分鏡成本前，請查閱目前 ToAPIs 目錄和你的帳戶報價。
官方廠商合約 往往帶有年度承諾、席位配額和預付門檻。ToAPIs 通常按量計費——請以帳戶上的現行條款為準。
從提示詞層控制支出：使用帶版本的模板，一次只改一個變數，並在客戶端超時後先查狀態，再決定是否重新提交。
關於基礎 H3、canonical Max 與 Turbo 的取捨，請看選型指南，不要依賴未經驗證的速度或畫質分數。

6. 常見問題

結構化問答見文章 frontmatter 中的 FAQ。摘要：提示詞以運鏡意圖開頭；複合運鏡是提示詞寫法而非保證語法；同樣寫法適用於首幀模式；括號標籤不是官方 API 參數。

7. 行動清單

在 ToAPIs 控制台領取 API Key。
用 minimax-h3、ratio: "16:9" 和 6 秒時長冒煙測試 cURL 示例。
接入提示詞助手，保存模板版本，並以 180 秒為輪詢截止時間。
接下來閱讀 H3 API 請求約定和自動化 R2V 流水線。

MiniMax H3 提示詞指南：如何用 API 寫出電影級運鏡

MiniMax H3 提示詞指南：如何用 API 寫出電影級運鏡

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

2. 運鏡提示詞模式

3. 生產級實作：cURL 與 Python

步驟 1：cURL 提交

步驟 2：Python 提示詞助手與輪詢

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

5. 定價與 FinOps ROI

6. 常見問題

7. 行動清單

本文提及的模型與介面

minimax-h3

minimax-h3-max

minimax-h3-max-turbo

相關技術文章

用 MiniMax H3 API 搭建自動化圖生影片（R2V）流水線

Seedance 2.0 Mini API 評測：低成本高吞吐影片生成

用 Seedance 2.0 生成 4K AI 影片：提示詞與參數最佳實踐