活动规则说明（字段驱动，不写死日期）
本段文案由活动公开配置字段生成：额度、窗口与并发只读 GET /v1/campaigns/h3-cn（匿名可查，带 Key 追加个人 quota 四元组 available/reserved/used/reset_at）。窗口未拍板前本页一律写「以活动页为准」，绝不预填日期。
| 免费范围（route 白名单） | 仅 minimax-h3-fast-local 与 minimax-h3-fast-hd-local（-local 别名形式）；Fast 实测 864×486，HD 为增强档实测 1728×972；画面 16:9 固定、自带音轨 |
| 额度向量 | buckets.fast.daily_seconds / buckets.hd.daily_seconds（输出秒/主体/自然日）；数字以活动页实时发布为准，缺省即「以正式发布为准」 |
| 账期与重置 | Asia/Shanghai 自然日；reset_at = 下一自然日 00:00（+08:00）；零余额账号活动额度内全程可用（0 元结算，无需充值） |
| 统一截止 | starts_at / stops_accepting_at / execution_buffer_ends_at / download_retention_ends_at / hard_ends_at 五字段统一收口（非滚动窗口）；具体时间以活动页为准 |
| 额度用尽 | 429 campaign_quota_exhausted：明确停止，绝不自动回退付费/海外路径；等自然日重置或明示改走付费口径 |
| 单主体并发 | 运行 1 + 等待 2（第 4 单 429 campaign_subject_busy）；批量任务请串行等终态，一单一等 |
| 受控调用默认值 | 提交 ≤10 RPM/主体、轮询 ≤30 RPM/主体（间隔 5-10s，勿低于 5s）；429 一律按 Retry-After 头退避；campaign_queue_full 的 Retry-After ≤ 600s |
| 暂停与排空 | operations 块：accept_open=false 停止接新、dispatch_open=false 暂停派发、draining=true 排空（等待单会被终止）；见信号即停投，已受理任务不受影响 |
| 产物与下载 | video.url 为签名 URL（终态后 24 小时内有效，超期重新查询即得新签名）；产物保留 ≤14 天，以活动页 download_retention_ends_at 为准 |
最小路径三步（curl）
提交返回 202 与 job id（形如 vidjob_*，字段是 id）；轮询 GET /v1/video/jobs/{job_id} 到终态（queued → running → succeeded | failed | cancelled）；succeeded 后从 video.url 下载预签名 mp4。以下为真实可重放的请求形状（prompt 必填非空；duration_seconds 取 4-15 整数秒，计费按实测输出秒）。
curl https://modelxing.com/v1/video/generations \
-H "Authorization: Bearer $MODELXING_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"minimax-h3-fast-local","prompt":"一只橘猫在阳光窗台上伸懒腰，写实风格，镜头缓缓推进","duration_seconds":4}'curl https://modelxing.com/v1/video/jobs/<job_id> \
-H "Authorization: Bearer $MODELXING_API_KEY"curl -o h3-cn-sample.mp4 "<video.url>" # 终态响应 video.url；签名 24h 内有效| 202 + id | 已受理，立刻把 job id 持久化到本地文件（恢复锚点） |
| video.url | succeeded 后出现；下载后校验 size>0 且文件头含 ftyp |
| cost 块 | 终态回显 amount/currency/duration_seconds（活动单 0 元结算） |
完整示例三件套（Python / TypeScript / curl）与恢复模式
仓库 examples/h3-cn/ 提供三件完整可运行示例（本页下方可整包下载），共同实现：读凭证走环境变量（绝不硬编码）→ 提交 → job id 写入本地状态文件 → 限频轮询（Retry-After 服从、尝试/截止上限）→ 下载并校验（size>0 + mp4 ftyp 头）→ 打印成本回显与状态。脚本重启后用恢复模式只查询旧任务、绝不重新随机提交；响应不明（UNKNOWN/5xx）按「结果确认中」处理：查询先行、不重派、不本地判失败退款。控制台侧同 job 的恢复深链为 /dashboard/video-jobs?job=<job_id>。
export MODELXING_API_KEY='<你的 API Key>' # 只进环境变量
python3 run_video_job.py --model minimax-h3-fast-local --duration 4
python3 run_video_job.py --resume # 重启后只查询既有 job idnpx tsx run_video_job.ts --model minimax-h3-fast-hd-local --duration 4
npx tsx run_video_job.ts --resume # 恢复模式./curl_min.sh # 提交 + 轮询 + 下载 + 校验
RESUME=1 ./curl_min.sh # 只查询既有 job id| run_video_job.py | Python 标准库（urllib），>= 3.9，无第三方依赖 |
| run_video_job.ts | Node 内置 fetch，>= 22，无第三方依赖 |
| curl_min.sh | bash + curl + python3（仅 JSON 解析） |
| 状态文件 | ./h3-cn-jobs/job-<model>.json（job id + Idempotency-Key + 参数） |
| 整包下载 | /downloads/h3-cn-examples.zip（同仓库 examples/h3-cn/；含 README 真实运行记录与错误码表） |
错误码表（码 / HTTP / 含义与建议动作）
活动域错误全部携带机器码（error.code）；429/503 带 Retry-After 头，窗口类 403/429 附带 reset_at（unix 秒）。响应不明一律按「结果确认中」：查询先行，不重派、不退款。发布后实测补录：活动域 429 族与 quota 类的真实触发样例将在活动发布后补入本页；当前免费语义以本表与契约为准。
| invalid_duration · 400 | 时长超出 4-15 整数秒。修正 duration_seconds 后重提交（预扣前拒绝、零费用） |
| unknown_parameter · 400 | strict 契约模式拒收未知字段（不静默丢弃）。删除未知字段重提交 |
| video_job_submit_rejected · 400 | upstream 拒绝（如 prompt 为空、参考图 host 不在 allowlist）。看 error.message 的 upstream_message 修正 |
| video_pricing_unavailable · 400 | 该 resolution 不在价面（活动两 SKU 固定输出档）。去掉 resolution 参数 |
| reference_audio_requires_visual · 400 | 音频不能作唯一参考，必须至少搭配一张参考图/视频 |
| video_job_too_many_reference_images · 400 | 参考图超过 4 张上限 |
| missing_api_key / api_key_malformed · 401 | 鉴权失败。检查 Authorization: Bearer 头与 Key 完整性 |
| campaign_not_published / campaign_unconfigured · 403 | 活动未发布/未配置。查活动页与 GET /v1/campaigns/h3-cn |
| campaign_not_started · 403 | 活动未开始（等 starts_at；响应附 reset_at）。到点再投 |
| campaign_accept_paused · 429 | 暂停接新（operations.accept_open=false）。停投，恢复后再提交 |
| campaign_draining · 429 | 排空中（operations.draining=true）：等待单会被终止。不要再新增等待 |
| campaign_ended · 403 | 活动已结束：停止接新；既有任务在下载保留期内照常查询/下载 |
| campaign_quota_exhausted · 429 | 当日免费额度用尽：明确停止——绝不回退付费/海外路径；等自然日（北京时间 00:00）重置或明示改走付费口径 |
| campaign_submit_rate_limited · 429 | 提交限流（10 RPM/主体）。按 Retry-After 退避后重试 |
| campaign_status_rate_limited · 429 | 轮询限流（30 RPM/主体）。拉长间隔到 5-10s 以上，按 Retry-After 退避 |
| campaign_subject_busy · 429 | 单主体运行 1 + 等待 2 已满。等在途任务到终态再提交（批量请串行等终态） |
| campaign_queue_full / queue_full · 429 | 队列满（Retry-After ≤ 600s）。按头退避；重试仍满则降低提交节奏 |
| campaign_idempotency_conflict · 409 | 同一 Idempotency-Key 配了不同请求体。换新键或保持同键同参（活动域：同键同参重放返回原 job，不产生新单） |
| cancel_too_late · 409 | 任务已终态，取消无效；按终态处理即可 |
| video_job_not_found · 404 | job id 拼错、跨主体查询或超保留期（同形响应不泄露存在性）。核对本地 job id 文件 |
| UNKNOWN（5xx / store 类 / 网络失败） | 结果确认中：查询先行——拿持久化 job id 继续轮询，绝不重派新单、绝不本地判失败退款 |
幂等语义：活动单与付费单必须分清
活动（免费）单：Idempotency-Key 同键同参重放返回原 job（活动账本指纹域），同键异参返回 409 campaign_idempotency_conflict——示例因此把幂等键与 job id 一起持久化，重试安全。付费单：公开面 idempotency_key 不防重（契约 §3.6 硬标注：同键两次=两单两扣费）——付费口径的重试防重必须由调用方自行实现（例如先查再投）。示例输出的成本回显会区分两种情形。
| 活动单同键同参 | 返回原 job（原 video.url / cost），不产生新单、不重复扣额度 |
| 活动单同键异参 | 409 campaign_idempotency_conflict，拒绝提交 |
| 付费单任意同键 | 不防重：两次提交=两个 job、两条独立结算链（调用方自查再投） |