视频生成

AsterMesh 提供 Sora 兼容的视频任务接口。视频生成采用异步流程：提交请求后先取得任务编号，等待任务完成，再下载视频。

本页以 h3 为例，使用一张参考图片和提示词，请求生成 4 秒、480p 的视频。

接口地址

视频 API 的 Base URL：

https://console.astermesh.cn/v1

下方 curl 示例已包含完整地址，无需再次拼接 /v1。素材 URL 使用上传接口实际返回的地址，例如 https://s3.anystarx.com/h3/file_xxx；保留这个地址的域名和路径。

开始前

1. 在 AsterMesh 控制台准备具有视频模型访问权限的 API Key，参见 账号与 API Key。
2. 准备一张参考图片，例如 cat.png，并在图片所在目录打开终端。
3. 将下方的 YOUR_API_KEY 换成自己的密钥，设置后在同一个终端依次执行四步操作。

export ASTERMESH_API_KEY="YOUR_API_KEY"

示例中的 file_xxx 和 task_xxx 都是占位符。需要分别替换为上传后得到的真实文件 URL、创建任务后得到的真实任务编号。

1. 上传参考图片

curl https://console.astermesh.cn/v1/files \
  -H "Authorization: Bearer $ASTERMESH_API_KEY" \
  -F "file=@cat.png"

@cat.png 表示读取本地图片文件。如果图片在其他目录，改成实际路径，例如 file=@/path/to/cat.png。

上传使用表单格式；-F 会让 curl 设置相应的请求头，此处无需添加 Content-Type: application/json。

上传成功后，从返回结果中复制完整的文件 URL。例如：

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

把这个真实 URL 填入下一步的 conditions[0].url。示例地址不能直接当作已经上传的素材使用。

2. 创建视频任务

将 conditions 中的图片 URL 替换为第一步返回的真实地址，再发送请求：

curl https://console.astermesh.cn/v1/videos \
  -H "Authorization: Bearer $ASTERMESH_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"
      }
    ]
  }'

请求被接受后，从返回结果中复制任务编号，供后续查询和下载使用。下面用 task_xxx 代表这个编号。

取得任务编号表示已提交任务，是否生成成功还需要查看任务状态。保存这个编号，后续查询始终使用同一个编号。

示例参数

这是一组完整的 h3 请求示例。其他模型、任务类型、时长、清晰度及素材限制，以对应模型的接口说明和实际返回为准。

Sora 兼容范围

视频任务采用 Sora 风格的创建、查询和下载路径。本例的 task、resolution、conditions 是模型接入使用的扩展字段；接入时按本页请求格式传递。

model: "h3" 指定的是本例的模型。接入官方 SDK 或其他客户端前，需要确认它能传递这些扩展字段和本例的 JSON 请求体。

3. 查询任务状态

把地址中的 task_xxx 替换为第二步返回的真实任务编号：

curl https://console.astermesh.cn/v1/videos/task_xxx \
  -H "Authorization: Bearer $ASTERMESH_API_KEY"

查看返回结果中的 status：

• status 为 completed：生成已完成，可以继续下载。
• 返回结果表示仍在等待或处理中：间隔一段时间后，再查询同一个任务。
• 返回结果表示任务失败：停止等待，查看失败原因并排查参数或素材。
• 查询请求本身返回 HTTP 错误：先根据错误信息处理；一次查询失败不等于生成任务已经失败。

“轮询”就是定期重复这个查询请求。简单脚本可先采用每 5～10 秒查询一次的间隔，并设置等待上限；这是客户端的起始配置建议，具体频率以服务端限流提示为准。达到等待上限后保留任务编号，稍后仍可查询已有任务。

4. 下载视频

确认 status 为 completed 后，使用同一个任务编号下载：

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

-L 让 curl 跟随下载地址的跳转，-o out.mp4 将视频保存到当前目录。--fail 让 HTTP 错误导致命令失败，避免把错误响应当作视频保存。

常见问题

其他状态码的处理方式见 故障排查。