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 视频：提示词与参数最佳实践