EcoPhase 兼容 MiniMax-H3 V2 格式视频生成接口，支持文生视频（T2VA）、图生视频（I2VA）和多模态参考生视频（R2VA）。目前输出固定为 768P、24 FPS、MP4/H.264、4–15 秒，暂不提供 2K。完整的请求/响应格式见 API 参考。

视频生成暂不计费，但请求仍需 video_generation 服务的 API Key，并受租户与凭据维度的限流。

请求地址与鉴权

在视频生成控制台的“API 接入”页面创建API Key。

export VIDEO_API_BASE_URL="https://ecotoken.ecophase-ai.com"
export VIDEO_API_KEY="YOUR_VIDEO_GENERATION_API_KEY"

创建接口为 POST /v2/video_generation。

Idempotency-Key 是 EcoPhase 的安全重试扩展：相同键加相同请求返回同一任务；相同键配不同请求返回 409。若创建结果未知，就用原键和完全相同的请求体重试。

提示词优化（Context IR）

EcoPhase 在提交视频生成前会用 Context IR 自动优化提示词，提升生成质量。请求会经历 context_ir_queued → context_ir_running 阶段，优化后的提示词可通过查询接口在 task.context_ir.optimized_prompt 中获取；Context IR 失败会使整个任务失败（failed_phase=context_ir）。

默认开启。可用顶层字段 context_ir_enabled 控制，可选布尔值，默认为 true：

• true（默认）：启用 Context IR，提示词先优化再提交视频生成。任务成功时按次计入 Context IR 费用；任务失败或取消则整笔免收。
• false：关闭 Context IR，跳过提示词优化，直接用原始提示词提交视频生成；任务不经过 Context IR 阶段，也不产生 Context IR 计费。

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "清晨薄雾中的山谷，镜头缓慢向前推进"}
  ],
  "resolution": "768P",
  "duration": 5,
  "ratio": "16:9",
  "aigc_watermark": false,
  "context_ir_enabled": false
}

文生视频 T2VA

content 里只放一个非空 text 项。T2VA 的 ratio 必填，必须是下文 6 个固定比例之一，不能是 adaptive。

curl "https://ecotoken.ecophase-ai.com/v2/video_generation" \
  -H "Authorization: Bearer $VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "清晨薄雾中的山谷，镜头缓慢向前推进"}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "aigc_watermark": false
  }'

图生视频 I2VA

content 用 image_url。首帧 first_frame 与尾帧 last_frame 均可选、各最多一张。每张最大 30 MiB。图生视频的宽高比由首帧决定（只有尾帧时由该尾帧决定），ratio 固定为 adaptive。帧输入不能与 reference_image、reference_video 或 reference_audio 混用。在 EcoWeb 上传起始帧后会自动进入图生视频，无需另选模式。

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "人物转身看向镜头，背景灯光轻微闪烁"},
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {"url": "https://YOUR_ALLOWED_MEDIA_HOST/first-frame.png"}
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": {"url": "https://YOUR_ALLOWED_MEDIA_HOST/last-frame.png"}
    }
  ],
  "resolution": "768P",
  "duration": 8,
  "ratio": "adaptive",
  "aigc_watermark": false
}

多模态参考生视频 R2VA

多模态参考模式使用 reference_image、reference_video、reference_audio。它们可在同一个 content 中任意非空组合，但不能与首尾帧模式混用。

所有参考视频总时长不超过 15 秒，所有参考音频总时长也不超过 15 秒；两者分别计算，因此可以同时使用 15 秒参考视频和 15 秒参考音频。以上限制见 MiniMax-H3 V2 输入媒体规范，并以控制台当前发布的能力为准。

ratio 可省略并默认 adaptive，也可显式指定固定比例。省略或传 adaptive 时使用 768P 16:9（1344×768）。

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "保持参考素材中的人物、运镜与音乐节奏"},
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {"url": "https://YOUR_ALLOWED_MEDIA_HOST/subject.png"}
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {"url": "https://YOUR_ALLOWED_MEDIA_HOST/motion.mp4"}
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {"url": "https://YOUR_ALLOWED_MEDIA_HOST/music.wav"}
    }
  ],
  "resolution": "768P",
  "duration": 10,
  "ratio": "adaptive",
  "aigc_watermark": false
}

本地文件上传

MiniMax-H3 请求体通过 image_url、video_url 或 audio_url 引用媒体。在 EcoWeb 选择本地图片、视频或音频后，页面会自动上传并提交任务。

也可以传入可公开访问的 http 或 https URL。URL 不能指向本机或私网，并受接口公布的超时和文件大小限制。

成功响应

创建成功返回 HTTP 200：

{
  "task_id": "YOUR_TASK_ID"
}

拿到 task_id 后可查询单个任务或任务列表。

参数规则

客户端不能指定节点、GPU、工作流或内部部署 ID。

错误、幂等与限流

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "REQUEST_DESCRIPTION",
    "http_code": "400"
  },
  "request_id": "YOUR_REQUEST_ID"
}

• 400：JSON、字段、媒体角色、能力参数或当前任务操作无效；任务不存在、不属于当前租户，或已从兼容视图删除。
• 401：API Key 缺失、无效、未生效或已吊销。
• 403：API Key 没有所需的服务或作用域权限。
• 409：相同幂等键对应不同请求，或状态转换冲突。
• 415：请求体不是 application/json。
• 429：租户或凭据达到速率/容量限制；按 Retry-After 等待后重试。
• 503 或 504：视频生成服务暂时不可用或请求超时。

不要自动重试结果未知且没有幂等键的创建请求。不要把 API Key、媒体签名 URL 或下载 URL 写进日志、浏览器代码或源码仓库。