VR 视频生成结果通知（回调）

接口说明：

视频生成服务在任务结束（成功或失败）时，向服务提供方在管理后台配置的 callback_url 发起 HTTP 请求，将结果通知接入方（该 URL 由接入方提供，由部署方在系统中配置）。创建任务时不需要、也不支持在请求体里传回调地址；所有任务共用同一回调 URL。

回调触发时机

事件	`event` 字段值	说明
任务成功结束	`task.completed`	视频已上传 OSS 等业务完成后触发
任务失败	`task.failed`	下载、渲染、上传等步骤在通用异常路径失败时触发

说明：任务因 Worker 软超时等单独分支标记为 failed 时，当前实现可能不发送 task.failed 回调；建议同时通过「任务详情」接口轮询或核对最终状态。

请求方式：

项	值
方法	`POST`
URL	配置的 `callback_url`
`Content-Type`	`application/json`

服务侧会按 5s → 15s → 30s 间隔最多重试 3 次；若均失败，任务在平台侧仍会标记结果，但回调可能标记为失败（可在管理端查看 callback_status）。

Headers：

Content-Type：application/json;charset=UTF-8（与 application/json 等价）

请求体字段（JSON）

公共字段（成功与失败均包含）：

字段	类型	说明
`event`	string	`task.completed` 或 `task.failed`
`task_id`	int	任务 ID
`model_id`	string	模型 ID
`model_version`	string	模型版本
`render_type`	string	`6cube` / `panorama`
`status`	string	`completed` 或 `failed`（与事件对应）
`timestamp`	string	回调生成时间，ISO 8601 格式

成功时额外字段（event = task.completed）：

字段	类型	说明
`oss_url`	string	视频访问地址（可下载）
`video_size_mb`	number	视频大小（MB）
`video_duration`	number	视频时长（秒，若有）

对象存储 Key（oss_key）在任务详情接口中可查；当前成功回调体中不单独携带 oss_key 字段。

失败时额外字段（event = task.failed）：

字段	类型	说明
`error_code`	string	错误码（如 `RENDER_CRASH`、`UNKNOWN` 等）
`error_message`	string	错误描述（可能被截断）

回调示例

成功：

{
  "event": "task.completed",
  "task_id": 12,
  "model_id": "your_model_id",
  "model_version": "1.0.0",
  "render_type": "6cube",
  "status": "completed",
  "timestamp": "2026-03-19T11:30:45.123456",
  "oss_url": "https://your-bucket.oss.aliyuncs.com/path/to/video.mp4",
  "video_size_mb": 56.15,
  "video_duration": 98.4
}

失败：

{
  "event": "task.failed",
  "task_id": 12,
  "model_id": "your_model_id",
  "model_version": "1.0.0",
  "render_type": "6cube",
  "status": "failed",
  "timestamp": "2026-03-19T11:20:00.000000",
  "error_code": "RENDER_CRASH",
  "error_message": "渲染进程退出码 -9: ..."
}

对接方建议

幂等：同一 task_id 可能因重试收到多次回调，建议按 task_id 做幂等处理。
快速响应：建议在 10 秒内 返回 HTTP 2xx，避免服务侧判定超时并重试。
安全（可选）：若需验签，请与部署方约定 Header 或 Body 中的签名算法；当前开源实现为明文 JSON POST。

响应规则

接入方处理完业务数据后，成功响应需满足回调接口规则中的约定，支持以下两种响应方式：

方式一： 当响应体的 Content-Type 为 text/plain;charset=utf-8 时，成功的响应字符串需要为 success（忽略大小写）

HTTP/1.1 200 OK
Content-Type: text/plain;charset=utf-8

success

方式二： 当响应体的 Content-Type 为 application/json;charset=utf-8 时，code=1 表示响应成功

{
  "msg": "ok",
  "code": 1
}

若响应失败，视频服务侧会按上文 5s → 15s → 30s 间隔最多重试 3 次（与通用文档中其他产品的重试间隔可能不同，以本页「视频生成服务」说明为准）。