MoonApiX Docs

简体中文

English

简体中文

English

外观

查询视频任务 ​

视频任务提交后需要通过查询接口读取状态、进度、结果 URL 和失败信息。即使配置了 Webhook，也建议保留主动查询能力。

方法与路径 ​

推荐统一查询入口：

http
GET /v1/tasks/{task_id}

兼容入口：

http
GET /v1/videos/{task_id}
GET /v1/video/generations/{task_id}
GET /v1/videos/{task_id}/content
GET /api/v3/contents/generations/tasks/{task_id}

兼容路径还支持按官方形状列出和取消任务：

http
GET /api/v3/contents/generations/tasks
DELETE /api/v3/contents/generations/tasks/{task_id}

兼容路径响应中的 content.video_url、content.last_frame_url 等字段可能只在任务 成功后出现。无论使用哪种入口，都先检查 status 和 error，再读取结果地址。

标准请求 ​

bash
curl https://moonapix.com/v1/tasks/task_01HX... \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>"

响应示例 ​

json
{
  "id": "task_01HX...",
  "object": "task",
  "trace_id": "2026060301010100000000000000000000",
  "request_id": "2026060301010100000000000000000000",
  "status": "succeeded",
  "model": "your-video-model",
  "created_at": 1710000000,
  "output": [
    {
      "type": "video",
      "url": "https://example.com/result.mp4"
    }
  ],
  "error": null
}

状态说明 ​

状态说明建议
pendingMoonApiX 已受理，等待提交或系统准备。稍后继续查询。
submitted已提交生成任务，等待开始处理。稍后继续查询。
running正在生成。继续等待，避免高频轮询。
succeeded已完成。读取结果 URL 并保存。
failed任务失败。查看 error、trace_id 和原始请求。
cancelled任务已取消。停止查询。

结果字段 ​

请先判断 status，再读取结果 URL：

  • status 为 succeeded 时，任务已成功，可以读取结果 URL。
  • status 为 pending、submitted、running、failed 或 cancelled 时，不要读取结果 URL。失败或未完成响应可能不会包含 output 或任何结果地址；failed 表示任务失败，请读取 error、trace_id 和 request_id。
  • /v1/videos/{task_id}/content 只建议在任务成功后使用。该兼容下载入口可能返回 302 跳转，请让 HTTP 客户端跟随重定向。

成功任务的结果可能出现在以下字段。不同兼容入口的响应结构可能不同，请以接口实际返回为准。

字段说明
output[].url推荐读取的视频结果 URL。
url部分兼容响应中的结果 URL。
video_url部分视频响应中的结果 URL。
result_url部分任务链响应中的结果 URL。
content.video_url视频查询或官方兼容查询中的视频结果地址。
content.last_frame_url可选，生成视频的尾帧图片地址；与输入尾帧参考图不同。

生成结果尾帧 ​

seedance-2.5-cl 已验证创建请求中的 return_last_frame=true。任务成功后，以下两种查询入口都可以返回 content.last_frame_url，无需开启 raw 模式或获取完整原始报文。其他模型是否支持，请查看对应模型页。

GET /v1/videos/{task_id} 的成功响应主要字段：

json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/result.mp4",
    "last_frame_url": "https://example.com/last-frame.jpg"
  }
}

GET /api/v3/contents/generations/tasks/{task_id} 的成功响应主要字段：

json
{
  "id": "task_xxx",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/result.mp4",
    "last_frame_url": "https://example.com/last-frame.jpg"
  }
}

id 均为 MoonApiX 公共任务 ID；/v1/videos 返回的 task_id 与 id 相同。官方兼容响应不要求额外的 task_id 字段。

  • 先确认 status=succeeded 且没有错误，再读取图片地址。content.last_frame_url 是独立图片 URL，不是视频 URL。
  • 尾帧是可选结果。未请求、模型未产出或没有可用的尾帧地址时，该字段可能省略；不要用视频地址代替。
  • 创建请求中的 last_frame_url 或参考素材的 role=last_frame 表示输入尾帧参考图，不能替代 return_last_frame=true。
  • 根据图片下载响应的 Content-Type 识别实际格式，不要固定要求 PNG；seedance-2.5-cl 已验证返回 JPEG。
  • 直接使用返回的完整图片 URL。地址不保证永久有效，需要长期保存时及时下载到自己的存储。

结果 URL 策略 ​

成功任务可能返回经过 MoonApiX 策略批准的直达媒体 URL，也可能返回 MoonApiX 管理的媒体 URL。两者都是客户可用结果；请直接使用接口实际返回的完整地址，不要按域名判断任务是否成功，也不要强制改走内容下载入口。

客户端集成时请遵循：

  • 不要根据结果 URL 推断模型能力或自行选择其他下载入口。
  • 不要自行拼接或改写结果 URL。
  • 保存接口返回的完整 URL，包括可能存在的签名查询参数；缺少或改写参数可能导致下载失败。
  • 如果业务需要长期归档、二次分发或去除临时签名依赖，请在业务侧下载后保存到自己的存储。

内容下载入口 ​

GET /v1/videos/{task_id}/content 是兼容兜底入口，只应在任务 succeeded 且查询响应没有提供可用结果 URL 时调用。该接口可能返回 302 跳转，也可能返回代理视频流；客户端请使用 curl -L 或在 SDK 中开启自动重定向。

bash
curl -L https://moonapix.com/v1/videos/task_01HX.../content \
  -H "Authorization: Bearer <MOONAPIX_API_KEY>" \
  -o result.mp4

轮询建议 ​

  • 前 30 秒可以每 3 到 5 秒查询一次。
  • 长任务建议逐步拉大间隔，例如 10 秒、20 秒、30 秒。
  • 任务进入成功、失败或取消状态后停止轮询。不要仅凭响应里出现 URL 字段判断任务成功。
  • 在业务系统保存最终 URL 和原始响应，便于后续排查。

相关页面 ​