MiniMax H3 API 接入教程
从第一次请求，到下载成片。

02 / PRICING

H3 API 生成 10 秒视频多少钱？

下表读取本站当前 API 报价。实际接入时读取 /videos/options 并计算本次请求的 expected_points，不要把示例金额写死。

无参考视频、不选高清化。人民币按 100 积分约合 1 元折算，不含充值赠送，不代表最低充值额或完整订单总价。

网页与 API 视频活动 4 折 · 截止 2026-11-30 14:05:44（北京时间）

报价读取时间：2026-11-03 23:46:56（北京时间）。价格会随活动与配置变化，请以提交前确认的费用为准。

03 / REQUEST

文字、图片和视频参考怎么传？

第一次接入可从普通文生视频开始：creation_type=general，不提供参考素材，选择时长和档位。先跑通创建、查询、下载，再加入参考素材。

提交前读取 /videos/options：available 为 false 时暂不提交；带参考视频还需 reference_video_available=true，视频编辑和人物替换还需 specialized_available=true。素材需先上传并完成校验；时长与宽高使用完成接口返回的真实素材信息。

04 / PYTHON

Python：生成、查询和下载一个视频。

准备 Python 3 和 requests（安装命令：python -m pip install requests），将 API Key 放入环境变量 API_KEY。下面示例与工作台开发者文档共用，默认创建标准档、10 秒、16:9、768p 的纯文字视频，不选择 2K 高清化。

import json, os, time, uuid
from pathlib import Path
import requests

base = os.getenv("API_BASE_URL", "https://xzanime.com/api/v1").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["API_KEY"]}

def build_request(model):
    duration = 10
    upscale_2k = False  # True 时将高清处理价格加入总报价。
    quality = next(t for t in model["tiers"] if t["tier"] == "standard")
    # 生成和 2K 分别按活动比例四舍五入，再相加；不要先对每秒单价打折。
    percent = model.get("promotion_snapshot", {}).get("percent", 100)
    def activity_price(points):
        return (points * percent + 50) // 100
    return {"creation_type": "general", "model": model["model"], "resolution": model["resolution"],
            "prompt": "云海之上，一条蓝鲸缓缓游过未来城市，镜头平稳跟随。",
            "duration": duration, "aspect_ratio": "16:9", "asset_ids": [],
            "tier": quality["tier"], "quality_enhance": True, "upscale_2k": upscale_2k,
            "expected_points": activity_price(quality["effective_points_per_second"] * duration)
                + (activity_price(model["effective_upscale_points_per_second"] * duration) if upscale_2k else 0)}


# 同一记录文件只代表一次生成。新视频请明确选择另一个文件名。
state_path = Path(os.getenv("VIDEO_REQUEST_FILE", "h3-request.json")).resolve()
job_id = os.getenv("VIDEO_JOB_ID", "")
state = None
if not job_id:
    if state_path.exists():
        state = json.loads(state_path.read_text(encoding="utf-8"))
        if state["base"] != base:
            raise RuntimeError("记录的 API 地址不同，请核对 VIDEO_REQUEST_FILE")
        job_id = state.get("job_id", "")
    else:
        options = requests.get(base + "/videos/options", headers=headers, timeout=30)
        options.raise_for_status()
        model = options.json()
        if not model["available"]:
            raise RuntimeError("视频服务暂不可用")
        # 发起请求前持久保存编号和内容；文件写入失败时不会提交生成。
        state = {"base": base, "request_key": str(uuid.uuid4()), "body": build_request(model)}
        with state_path.open("x", encoding="utf-8") as record:
            json.dump(state, record, ensure_ascii=False, indent=2)
            record.flush()
            os.fsync(record.fileno())

if job_id:
    response = requests.get(base + "/jobs/" + job_id, headers=headers, timeout=30)
else:
    # 超时或进程重启后重放原请求，不重新报价或更换编号。
    response = requests.post(base + "/videos/generations", json=state["body"],
        headers={**headers, "Idempotency-Key": state["request_key"]}, timeout=60)
response.raise_for_status()
job = response.json()
print("保存任务编号：", job["id"])
if state is not None and not state.get("job_id"):
    state["job_id"] = job["id"]
    # 原子替换，避免写入中断损坏原记录；记录中不保存 API Key。
    temporary = state_path.with_name(state_path.name + "." + uuid.uuid4().hex + ".tmp")
    with temporary.open("x", encoding="utf-8") as record:
        json.dump(state, record, ensure_ascii=False, indent=2)
        record.flush()
        os.fsync(record.fileno())
    temporary.replace(state_path)
for _ in range(180):
    if job["status"] in ("succeeded", "failed") or job["recovery_paused"]:
        break
    time.sleep(10)
    response = requests.get(base + "/jobs/" + job["id"], headers=headers, timeout=30)
    response.raise_for_status()
    job = response.json()
if job["status"] != "succeeded":
    raise RuntimeError(f"请保留任务编号后继续查询，勿重复创建：{job}")
print("实际消费：", job["charged_points"])
# 读取本次文件的下载协议；所有操作均可通过 API 完成。
download_base = base + "/videos/" + job["id"]
response = requests.get(download_base + "/download-policy", headers=headers, timeout=30)
response.raise_for_status()
policy = response.json()
print(json.dumps(policy, ensure_ascii=False, indent=2))
# input 仅演示命令行确认；接入应用使用自身的确认流程，无需网页登录或 Cookie。
if input("是否接受以上下载协议？输入 yes 继续：").strip().lower() != "yes":
    raise SystemExit("未确认下载。视频已保存；设置 VIDEO_JOB_ID=" + job["id"] + " 可继续下载。")
response = requests.post(download_base + "/download", headers=headers, timeout=30,
    json={"accepted": True, "version": policy["version"], "content_token": policy["content_token"]})
response.raise_for_status()
download = response.json()  # url 为签名下载地址，expires_in 为有效秒数（900）。
# 签名地址无需 Bearer Key；不要把平台 API Key 转发到文件存储服务。
with requests.get(download["url"], stream=True, timeout=60) as media:
    media.raise_for_status()
    with Path("video.mp4").open("wb") as output:
        for chunk in media.iter_content(1024 * 1024):
            output.write(chunk)

示例提示词用于演示接口调用，不是视频展示片的原始生成记录。代码不会在此页面自动执行。

05 / DOWNLOAD

生成完成后，如何通过 API 下载？

以下路径均相对于 https://xzanime.com/api/v1，{id} 使用已完成任务的 id。读取协议和提交确认使用同一个 Bearer API Key；确认由接入方在自己的应用或业务流程中完成，不要求用户返回网站操作。

1. 任务 status=succeeded 后，GET /videos/{id}/download-policy 读取当前文件的下载协议，返回 version、content_token、notice、article、law_url、responsibilities 等字段。向使用者提供协议内容并取得确认；无需打开网站或先播放视频。

2. POST /videos/{id}/download，Content-Type 为 application/json，JSON 为 {"accepted":true,"version":"本次协议返回的 version","content_token":"本次协议返回的 content_token"}。accepted 必须为布尔值 true；version 和 content_token 原样使用本次协议的返回值，不要写死，也不要跨作品或分辨率版本复用。

3. 成功返回 HTTP 200 和 {"url":"签名下载地址","expires_in":900}，直接 GET url 保存文件，无需也不要发送平台 API Key。地址过期后，对原任务重新读取协议并确认获取新地址，不会重新生成或扣费。

4. 下载版本不包含平台添加的显式 AI 提示文字或语音提示，仍保留文件内的隐式 AIGC 标识；历史作品以协议的 notice 与 metadata_verified 为准。播放接口提供带显式提示的播放版本。

5. 默认下载最终成片（已成功高清化时为 2K）。需要原分辨率版本时，读取协议与提交下载两个接口都带 original=true；这仅选择分辨率版本。native_video_url 和 /content?original=true 属于播放接口，不能据此判断是否带显式标识。

6. 收到 HTTP 409 且响应 JSON 的 detail.code=ai_label_consent_required，表示请求了需要下载确认的源片入口（如 /jobs/{id}/files/0 或 /videos/{id}/content?download=true）。请保留原任务 id，改走以上协议与确认接口；无需重新生成、重复扣费或跳转网页。确认成功后使用返回的 url，不要重试原 files/content 地址；确认不会把这些入口永久解锁。

7. POST /download 返回 400 且提示未接受协议时，应先取得确认再提交 accepted=true；返回 409 且提示文件或协议已更新时，重新读取同一作品、同一分辨率版本的 download-policy，再确认并提交最新字段。不要把所有 409 当成同一种错误，也不要默认替用户接受协议。

06 / TROUBLESHOOTING

等待、超时与下载问题怎么处理？