MoonApiX Docs

Appearance

查询视频任务 ​

视频任务提交后需要通过查询接口读取状态、进度、结果 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

标准请求 ​

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": "seedance-2.0-kz-fast",
  "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。failed 表示任务失败，请读取 error、trace_id 和 request_id。
  • /v1/videos/{task_id}/content 只建议在任务成功后使用。

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

字段说明
output[].url推荐读取的视频结果 URL。
url部分兼容响应中的结果 URL。
video_url部分视频响应中的结果 URL。
result_url部分任务链响应中的结果 URL。

结果 URL 策略 ​

不同视频模型的结果 URL 策略可能不同。成功任务可能返回 MoonApiX 托管媒体 URL，也可能返回模型服务提供的可公网访问媒体直链；MoonApiX 不会默认把所有视频结果都自动转存为同一个域名。

客户端集成时请遵循：

  • 不要写死结果 URL 域名。
  • 不要自行拼接或改写结果 URL。
  • 保存接口返回的完整 URL，包括查询参数。
  • 如果业务需要长期归档、二次分发或去除临时签名依赖，请在业务侧下载后保存到自己的存储。

轮询建议 ​

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

相关页面 ​