# 视频任务

先提交生成任务，再查询进度并获取视频结果。

## 选择接口

支持统一视频接口的模型可使用下列流程。其他模型可能要求供应商原生任务接口，请以模型详情公布的端点为准。不要把同一请求体原样用于所有视频模型。

## 1. 提交任务

先将 `XINGSUAN_MODEL` 设为支持该接口、且允许 5 秒文生视频的模型 ID。以下示例的时长只是参数示范，不是全部模型通用的合法值。



```bash
curl 'https://api.xsopc.com/v1/videos' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "model": "$XINGSUAN_MODEL",
  "prompt": "A slow camera move through a sunlit forest",
  "seconds": "5"
}
JSON
```



提交成功后保存平台返回的任务 ID。返回任务 ID 表示任务已受理，不代表视频已生成。

## 2. 查询进度

把 `YOUR_TASK_ID` 替换为实际返回的 ID，使用同一账户的有效密钥查询。



```bash
curl 'https://api.xsopc.com/v1/videos/YOUR_TASK_ID' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY"
```



建议从间隔 3～5 秒开始轮询，并在长任务中逐步放宽间隔。根据返回状态判断排队、处理中、成功或失败；不同接口的状态名称和响应结构可能不同。

通用任务查询接口如下。它与原生视频查询的 JSON 结构不同，不要共用同一个解析器。



```bash
curl 'https://api.xsopc.com/v1/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY"
```



## 3. 获取结果

任务成功且模型支持该下载接口时，可下载视频；否则按任务返回的结果或素材列表获取。



```bash
curl --fail --location \
  'https://api.xsopc.com/v1/videos/YOUR_TASK_ID/content' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY" \
  --output result.mp4
```



结果链接和素材可能过期。拿到成功结果后及时下载，下载请求仍需相应权限。不要把带访问凭据的地址公开传播。

## 参考图片和视频

对于支持本地首帧图片上传的统一视频模型，可按下面的 multipart 格式提交；仍需确认该模型支持所用时长和上传方式。



```bash
curl 'https://api.xsopc.com/v1/videos' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY" \
  -F "model=$XINGSUAN_MODEL" \
  -F 'prompt=A slow camera move, preserve the main subject' \
  -F 'seconds=5' \
  -F 'input_reference=@reference.png'
```



多图参考、首尾帧、参考视频的字段和限制各不相同。上游只接受 URL 时，需要自行提供有效 URL，或由平台已启用的对象存储与对应适配完成转换，详见[文件与参考素材](/zh/files/)。

## 防止重复任务

任务查询不会重新提交生成。若提交时超时，不要立即反复点击生成；先检查控制台任务记录。时长、分辨率、参考素材及模型模式可能影响费用，实际以模型计费说明为准。