发起VR视频生成任务

接口说明：

客户通过此接口发起 VR 视频生成任务。实际部署时请将 {BASE_URL} 替换为服务对外地址（含协议与端口）。若部署在内网，域名由客户提供。

通用约定：

项	说明
协议	HTTPS（生产环境推荐）
数据格式	`application/json; charset=UTF-8`
HTTP 状态码	业务接口统一返回 200（成功/失败通过响应体 `success`、`code` 区分）
API 前缀	`/api/v1/{PROJECT_NAME}`，默认 `PROJECT_NAME` 为 `video_ms`，即 `/api/v1/video_ms`

请求路径：

{BASE_URL}/api/v1/video_ms/video/tasks

若部署时修改了环境变量 VIDEO_MS_PROJECT_NAME，请将路径中的 video_ms 替换为对应项目名。

请求方式：

POST

Headers：

Content-Type: application/json

（若网关或服务要求鉴权，请按部署方提供的 Token / API Key 等要求追加请求头。）

请求体字段：

字段	类型	必填	说明
`model_id`	string	是	模型 ID，长度 1–100
`model_version`	string	是	模型版本，长度 1–50
`render_type`	string	否	渲染模式，默认 `6cube`。可选：`6cube`（六面图）、`panorama`（全景图）

说明：

点位、素材路径等由 Worker 根据 model_id + model_version 从 CDN 的 settings.txt 等自动拉取，请求中无需传点位列表。
输出分辨率、帧率、码率、渲染线程数等由服务侧系统配置决定；同一 model_id + model_version 在系统中通常仅允许存在一条任务，重复创建会返回业务错误。
任务完成后的回调地址由服务提供方在管理后台统一配置（callback_url），不在本接口请求体中传递；详见 VR 视频生成结果通知（回调）。

请求示例：

POST /api/v1/video_ms/video/tasks HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "model_id": "your_model_id",
  "model_version": "1.0.0",
  "render_type": "6cube"
}

成功响应（HTTP 200）

响应体为统一包装结构：

字段	类型	说明
`code`	int	成功时为 `1`
`success`	bool	成功时为 `true`
`message`	string	提示信息
`data`	object	业务数据

data 字段（创建成功时）：

字段	类型	说明
`task_id`	int	任务主键 ID，后续查询、对账使用
`model_id`	string	与请求一致
`model_version`	string	与请求一致
`render_type`	string	实际渲染类型
`point_count`	int	创建时点位数（初始可能为 0，Worker 下载后会更新）
`status`	string	初始一般为 `pending`
`created_at`	string	创建时间（ISO 8601）
`celery_task_id`	string	异步任务 ID（可选，用于内部追踪）

成功示例：

{
  "code": 1,
  "success": true,
  "message": "任务已提交",
  "data": {
    "task_id": 12,
    "model_id": "your_model_id",
    "model_version": "1.0.0",
    "render_type": "6cube",
    "point_count": 0,
    "status": "pending",
    "created_at": "2026-03-19T10:00:00",
    "celery_task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

失败响应（HTTP 200）

success 为 false，code 大于 1，message 为错误说明（例如模型已存在任务、参数校验失败等）。

任务进度查询（可选）

如需轮询进度，可使用（具体以部署环境 OpenAPI 文档为准）：

GET /api/v1/video_ms/video/tasks/{task_id} — 任务详情（含 progress、status 等）

Swagger 文档地址一般为：{BASE_URL}/docs