MoonNexAI API 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://moonnexai.com/v1/tasks/task_01HX... \
  -H "Authorization: Bearer <MOONNEXAI_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
}

状态说明 ​

状态说明建议
pendingMoonNexAI 已受理，等待提交或系统准备。稍后继续查询。
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。

结果 URL 策略 ​

客户侧视频结果统一使用 MoonNexAI 自有受控地址，包括 media-nex.windfimusic.com 官方转存媒体 URL 或标准内容下载入口。media-nex.windfimusic.com 是由 MoonNexAI 管理、用于托管生成结果的安全媒体域名。请直接使用接口返回的完整地址。

客户端集成时请遵循：

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

内容下载入口 ​

GET /v1/videos/{task_id}/content 是兼容下载入口，只应在任务 succeeded 后调用。若结果已经存入 MoonNexAI 媒体存储，接口会优先返回 302 并跳转到 MoonNexAI 媒体 URL；客户端请使用 curl -L 或在 SDK 中开启自动重定向。若托管媒体暂不可用，接口可能回退为代理视频流。

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

轮询建议 ​

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

相关页面 ​