本参考面向视频生成（video_generation）服务的开发者，提供请求、响应和错误格式。

兼容基线为 MiniMax 官方的创建视频生成任务和文件上传接口。

所有请求都在请求头中携带 Authorization: Bearer <API_KEY>。除文件上传外，请求体媒体类型为 application/json。

概览

创建视频生成任务

POST /v2/video_generation

成功响应

创建成功返回 HTTP 200，响应体为 JSON：

{"task_id":"1d6085ca-1d9a-4d61-a4a6-30e02079990f"}

顶层字段

当前支持 768P、24 FPS、MP4/H.264，纯文本、首尾帧视频生成。 context_ir_enabled 决定是否启用 Context IR 提示词优化，默认为 true ，即启用提示词优化。

创建示例

curl -X POST "https://ecotoken.ecophase-ai.com/v2/video_generation" \
  -H "Authorization: Bearer ${VIDEO_API_KEY}" \
  -H "Idempotency-Key: video-create-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"MiniMax-H3",
    "content":[{"type":"text","text":"日出时分的高山湖泊，电影感运镜"}],
    "resolution":"768P",
    "duration":5,
    "ratio":"16:9"
  }'

content

每个 content 项都有一个必填的 type：

可用的 URL 形式为公开 HTTP(S)、mm_file://{file_id}，以及严格的Base64编码形式 data:<media-type>;base64,<standard-base64>。整个 JSON 请求体最大 64 MiB；大文件或需要复用的素材应先上传。

data:<media-type>;base64,<standard-base64> 为 Data URL（数据地址），用于把小文件直接编码进 JSON 请求，不需要先上传并获取公网 URL。 data:：表示后面不是普通网络地址，而是文件内容。 <media-type>：文件的 MIME 类型，例如 image/png、audio/mpeg。 base64：声明文件内容采用 Base64 编码，固定值。 <standard-base64>：原始文件经过标准 Base64 编码后的字符串。

角色为 first_frame、last_frame、reference_image、reference_video、reference_audio。单个不带角色的图片默认作为首帧；视频和音频输入使用对应的参考角色。

接受的场景：

• 仅文本
• 文本 + 首帧
• 文本 + 尾帧
• 文本 + 首帧与尾帧
• 文本 + 参考图片/视频/音频的任意合法组合

帧角色与参考角色互斥。首帧、尾帧各自最多出现一次。

媒体校验

ratio

• T2VA 的 ratio 必填，不能是 adaptive，为 21:9|16:9|4:3|1:1|3:4|9:16 之一。
• I2VA 由其输入推导比例：省略、adaptive 或其他看似合法的比例都被规范化为 adaptive。
• R2VA 默认 adaptive，可以调整为 21:9|16:9|4:3|1:1|3:4|9:16 之一。

查询单个任务

GET /v2/query/video_generation/{task_id}

响应格式

{
  "task": {
    "id": "1d6085ca-1d9a-4d61-a4a6-30e02079990f",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1787788800,
    "updated_at": 1787789100,
    "content": {"url": "https://SHORT_LIVED_DOWNLOAD_URL"},
    "resolution": "768P",
    "duration": 8,
    "usage": {"input_image_count": 1},
    "ratio": "adaptive",
    "task_type": "generation",
    "modality": "video"
  }
}

任务响应字段

任务状态监测

推荐使用 task.internal_status 监测任务的精确处理阶段；MiniMax 接口字段 task.status不能准确显示各个阶段。

task.context_ir 字段：

仅在 succeeded 时使用 task.content.url；该地址有效期较短，不应持久化或长期缓存。

task.context_ir 上报 enabled、status、original_prompt、optimized_prompt、token usage、started_at、completed_at，以及可选的 error。Context IR 失败会使整个任务失败并标记 failed_phase=context_ir。

计费语义

视频任务只在生成成功时计费：

• 任务终态为 `succeeded` 才收取任何费用：按实测输出秒数×分辨率档位计价，并计入本次生成的 Context IR 调用（context_ir.status=succeeded，每个任务按次计费）。
• 任务终态不是 `succeeded`（含 `failed`、`cancelled`、超时）时全部免收——输出视频、参考图像、输入音视频等视频侧行，以及 Context IR 行，一律不收取。提示词优化是通往视频的中间步骤而非独立交付物，视频没有生成即整笔释放预授权。
• 任务完全免费的两种情形：视频生成失败或取消，以及 Context IR 自身失败（未交付提示词）。
• 因此失败后使用新的幂等键安全重试，失败不会产生任何费用；同一幂等键重发不会重新执行、也不会新增扣费（7 天内返回原任务）。

查询任务列表

GET /v2/query/video_generation?page_num=&page_size=&filter.status=&filter.task_ids=&filter.model=

服务端按租户隔离。page_num 默认 1，page_size 默认 20，当前最大 20。列表只覆盖最近 7 天创建的任务。

Query 参数支持 filter.status、filter.task_ids（可重复，也兼容 filter.task_ids[]，最多 100 个小写规范 UUID）和 filter.model。响应：

{
  "items": [
    {
      "id": "1d6085ca-1d9a-4d61-a4a6-30e02079990f",
      "model": "MiniMax-H3",
      "status": "succeeded",
      "created_at": 1787788800,
      "updated_at": 1787789100,
      "content": {"url": "https://SHORT_LIVED_DOWNLOAD_URL"},
      "resolution": "768P",
      "duration": 5,
      "usage": {},
      "ratio": "16:9",
      "task_type": "generation",
      "modality": "video"
    }
  ],
  "total": 1
}

total 是最近 7 天内符合筛选条件的任务总数。

取消或删除任务

DELETE /v2/video_generation/{task_id}

排队任务只有在取消得到确认后才返回 action=cancelled,status=cancelled。确认期间任务仍可查询为 queued，DELETE 返回可重试的 503；若首次请求使用了 Idempotency-Key，重试时应继续使用同一个键。已经运行的任务不能取消并返回 400。成功或失败的终态任务可以从兼容列表中逻辑删除，返回 action=deleted,status=deleted。

成功后响应体：

{
  "task_id": "1d6085ca-1d9a-4d61-a4a6-30e02079990f",
  "action": "cancelled",
  "status": "cancelled"
}

deleted 仅描述删除操作结果；查询响应中的 task.status 不会出现 deleted。

文件上传与媒体管理

媒体通过公开 HTTP(S) URL 或托管文件引用。提供五个操作，全部限定在已认证用户的素材空间：同一用户的不同 API Key 和工作空间共享该空间；其他用户只能得到未找到响应，无法据此判断文件是否存在。

文件管理 JSON 响应复用以下对象：

上传

POST /v1/files/upload，multipart/form-data：必须包含一个 purpose=video_generation_input 字段和一个名为 file 的文件部分，不允许其他字段。请求总大小不超过 64 MiB；非法文件返回 HTTP 400 且不会被保留。文件通过 mm_file://{file_id} 引用，默认保留一天，也可以主动删除。

curl -X POST "https://ecotoken.ecophase-ai.com/v1/files/upload" \
  -H "Authorization: Bearer ${VIDEO_API_KEY}" \
  -H "Idempotency-Key: media-upload-001" \
  -F "purpose=video_generation_input" \
  -F "file=@./reference.mp4;type=video/mp4"

成功响应：

{
  "file": {
    "file_id": 424010985738629,
    "bytes": 1234567,
    "created_at": 1788148800,
    "filename": "reference.mp4",
    "purpose": "video_generation_input"
  },
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

列表

GET /v1/files/list?purpose=video_generation_input

成功响应返回当前用户仍有效的完整素材数组：

{
  "files": [
    {
      "file_id": 424010985738629,
      "bytes": 1234567,
      "created_at": 1788148800,
      "filename": "reference.mp4",
      "purpose": "video_generation_input"
    }
  ],
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

查询文件

GET /v1/files/retrieve?file_id=424010985738629

{
  "file": {
    "file_id": 424010985738629,
    "bytes": 1234567,
    "created_at": 1788148800,
    "filename": "reference.mp4",
    "purpose": "video_generation_input",
    "download_url": "https://download.example/reference.mp4"
  },
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

download_url 有效期较短，每次需要下载时应重新查询。

下载文件内容

GET /v1/files/retrieve_content?file_id=424010985738629

成功时响应体为文件字节流，并携带对应的 Content-Type，不是 JSON。客户端只需发送自己的 EcoPhase API Key。

删除

POST /v1/files/delete，注意删除请求使用 purpose=video_generation；上传与列表继续使用 video_generation_input。

{"file_id":424010985738629,"purpose":"video_generation"}

成功响应：

{
  "file_id": 424010985738629,
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

同一用户使用相同的 file_id 和 purpose 重试删除是幂等的。

错误封装

视频生成接口使用 MiniMax 兼容错误封装：

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

错误响应字段：

幂等

视频生成、文件上传和任务删除支持可选的 Idempotency-Key。键长度为 1–128 个安全 ASCII 字符，并限定在当前接口、服务、工作空间和认证用户内；同一用户更换 API Key 不改变回放身份。视频任务创建键的有效窗口为首次成功后七天。

操作完成后，相同键和相同请求返回之前的结果；同一个键对应不同请求时返回 409。第一个操作仍在处理中时，相同请求也可能收到 409，调用方应稍后使用完全相同的键和请求重试。删除任务不会释放原创建键；窗口到期后再次使用该键会创建新任务。