AnyStarX Wiki

通过 Sora 兼容规范的视频接口，以 h3 模型为例完成素材上传、任务提交、状态轮询与视频文件下载。

AnyStarX 提供兼容 Sora 规范的视频生成接口。由于视频渲染开销大、耗时较长，接口采用异步任务机制处理：客户端首先上传参考素材并提交生成请求获取任务编号，随后定期查询任务执行进度，待渲染完成后再通过下载接口拉取视频文件。

本文以 h3 模型为例，演示如何使用一张参考图片配合文本提示词，生成时长为 4 秒、分辨率为 480p 的视频文件。

接口端点概览

视频生成相关接口的基础 Base URL 统一使用：

https://console.anystarx.com/v1

各阶段的请求方法与路径划分如下：

请求方法	路由路径	功能说明
`POST`	`/v1/files`	上传参考图片素材，获取可被视频任务引用的文件 URL
`POST`	`/v1/videos`	提交包含提示词与素材引用的视频生成任务
`GET`	`/v1/videos/{task_id}`	查询指定任务的执行状态与渲染进度
`GET`	`/v1/videos/{task_id}/content`	下载渲染完成的视频文件

下文示例中的命令均包含完整的请求路径。在上传素材接口成功返回后，需记录实际返回的文件地址（例如 https://s3.anystarx.com/h3/file_xxx），并在第二步提交任务时传入该地址。

准备工作

在开始调用前，请确认完成以下准备：

登录 AnyStarX 控制台，准备好具备视频模型调用权限的 API Key，管理规范参考账号与 API Key。
准备一张本地测试图片（例如当前目录下的 cat.png）。
在本地终端中设置环境变量保存 API Key，便于后续命令复用：

export ANYSTARX_API_KEY="YOUR_API_KEY"

示例中的 file_xxx 与 task_xxx 为占位符，实际操作时请分别替换为上传后返回的真实素材 URL 和提交任务后返回的真实任务编号。

1. 上传参考素材图片

通过多部分表单（Multipart Form）向 /v1/files 接口上传本地参考图片：

curl https://console.anystarx.com/v1/files \
  -H "Authorization: Bearer $ANYSTARX_API_KEY" \
  -F "file=@cat.png"

参数中 @cat.png 表示读取当前工作目录下的文件。如果图片存储在其他目录，需指定绝对路径或相对路径。-F 选项会自动由 curl 构建多部分表单请求头，因此无需手动指定 Content-Type: application/json。

上传成功后，服务端返回的 JSON 数据中将包含文件访问 URL，例如：

https://s3.anystarx.com/h3/file_xxx

请复制该真实地址，用于在下一步的 conditions 数组中声明参考素材。

2. 提交视频生成任务

将第一步获取到的素材 URL 填入请求体中的 conditions[0].url，发起异步生成请求：

curl https://console.anystarx.com/v1/videos \
  -H "Authorization: Bearer $ANYSTARX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "h3",
    "task": "ref2va",
    "prompt": "一只猫在草地上跑",
    "seconds": "4",
    "resolution": "480p",
    "conditions": [
      {
        "type": "image",
        "url": "https://s3.anystarx.com/h3/file_xxx"
      }
    ]
  }'

请求成功受理后，服务端会返回本次任务的唯一标识符（即任务编号）。请将返回的 ID 保存在本地，后续的进度查询和视频下载均需依赖该编号。

请求参数说明

字段名称	示例取值	说明
`model`	`"h3"`	本次调用指定的视频生成模型标识符
`task`	`"ref2va"`	任务类型代码，本示例使用参考图生成任务代码
`prompt`	`"一只猫在草地上跑"`	描述预期生成场景的文本提示词
`seconds`	`"4"`	生成视频的目标时长（秒），本模型以字符串格式传递
`resolution`	`"480p"`	视频输出分辨率
`conditions`	数组对象	传入生成的参考条件，本例包含一张参考图片
`conditions[].type`	`"image"`	素材类型，声明为图片条件
`conditions[].url`	上传后返回的完整 URL	第一步调用上传接口实际取得的文件地址

上述参数构成了 h3 模型的完整调用载荷。其他视频模型的参数规范、时长档位和分辨率支持，以控制台模型页面的最新说明为准。

协议兼容说明

视频生成遵循 Sora 规范中的任务提交、状态轮询和内容下载路由结构。参数中的 task、resolution 与 conditions 属于特定模型接入所需的扩展字段。在将自研系统或 SDK 与该接口集成时，请确保代码能够完整序列化上述请求体字段。

3. 轮询任务执行状态

将请求地址中的 task_xxx 替换为第二步实际获得的任务编号，查询执行进度：

curl https://console.anystarx.com/v1/videos/task_xxx \
  -H "Authorization: Bearer $ANYSTARX_API_KEY"

解析响应数据中的 status 字段：

completed：视频渲染已完成，可以继续调用下载接口。
等待或处理中状态：服务端正在排队或渲染，建议在本地程序中等待 5 到 10 秒后重新发起查询。
失败状态：服务端渲染异常或输入的素材不符合模型约束，应读取响应中的失败原因排查问题。
查询接口返回 HTTP 错误：检查网络连通性或 API Key 权限，单次查询失败并不意味着后台渲染任务已终止。

在编写轮询脚本时，建议设置 5 至 10 秒的轮询间隔并设定最大等待超时时长，避免高频请求触发接口限流。

通过 GET 请求跟踪进度

等待视频渲染期间，只能通过 GET 请求查询任务进度。切勿通过重复发送 POST /v1/videos 请求进行探测，否则会反复创建全新任务并造成多次额度扣减。

4. 下载生成视频

在任务状态确认为 completed 后，使用相同的任务编号请求下载接口：

curl --fail --show-error -L https://console.anystarx.com/v1/videos/task_xxx/content \
  -H "Authorization: Bearer $ANYSTARX_API_KEY" \
  -o out.mp4

命令选项说明：

-L：使 curl 自动跟随服务端返回的 302 临时重定向，直接拉取文件存储节点上的实际媒体流。
-o out.mp4：将下载的媒体数据写入当前目录下的目标文件。
--fail：如果服务端返回 4xx 或 5xx 错误，curl 将直接报错退出，避免将错误说明网页保存为损坏的视频文件。

常见问题与排查方法

故障现象	建议排查方向
上传素材提示找不到本地文件	检查终端当前工作目录与文件名拼写，包含空格的本地路径需使用引号包裹
接口返回 401 或 403	检查 API Key 是否有效，以及账号是否开通了对应的视频生成模型权限
提交任务被服务端拒绝受理	对照示例核实 JSON 结构与字段类型，确认 `conditions[].url` 为真实上传成功的文件地址
提交或查询请求发生网络超时	如果已成功取得任务编号，直接对该编号发起查询，避免无序重复提交全新任务
任务执行超时长时间未结束	保持轮询并设定合理的超时上限，若达到业务超时阈值可记录编号稍后重新探测
下载操作返回文件损坏或无法播放	确认任务状态已变更为 `completed`，并确保下载命令中包含了 `-L` 参数以跟随重定向

视频生成

本页内容