SEED VIDEO PLATFORM

视频生成业务接口

使用统一接口提交文本、图片、视频与音频素材，异步获取最终成片。平台负责内部处理与素材校验。

API Base URLhttps://api.gate.ayshq.com两套接口都调用这个地址，路径格式不同

查看更新历史查看快速开始

历史更新

只需三个业务步骤

创建 Token

在用户控制台创建 API Token，仅保存到服务端环境变量。

提交任务

文本可直接提交；素材调用 SDK 上传后作为输入引用。

轮询并下载

任务成功后获取短期有效的 output_url 下载成片。

接口请求地址：https://api.gate.ayshq.com平台提供两套互不影响的接口：现有业务接口使用 /v1/...；已接入火山官方协议的客户使用 /api/v3/contents/generations/tasks 系列。完整地址均为「API Base URL + 接口路径」。

GET/v1/credits/balance

提交任务前查询可用人民币余额。

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Idempotency-Key: your-business-order-id

GET/v1/credits/balance

查询当前用户的人民币余额，金额字段统一以分为单位。

请求参数

无路径参数和请求体。

返回 200

字段类型说明

total_balance_centsinteger账户余额总额，包含冻结余额

available_balance_centsinteger当前可用余额

frozen_balance_centsinteger处理中任务冻结金额

consumed_balance_centsinteger历史累计消费金额

currencystring固定为 CNY

updated_atdatetime余额更新时间

{
  "total_balance_cents": 5000,
  "available_balance_cents": 4853,
  "frozen_balance_cents": 147,
  "consumed_balance_cents": 0,
  "currency": "CNY",
  "updated_at": "2026-08-27T03:00:00Z"
}

工作流

素材上传对业务方是一项操作

SDK 的 upload_asset / uploadAsset 会自动完成签名地址申请、文件直传和上传校验。调用方只拿到可用于任务的 asset_id。

本地素材SDK 上传asset_id创建任务最终视频

场景示例

七种多模态组合

文本在带素材的场景中可选。请在提示词中清楚说明每个参考素材的用途，例如“参考视频 1 的动作节奏，使用音频 1 作为背景音乐”。

下载包中的多模态示例遇到参考音频会自动开启 generate_audio=true。直接调用 HTTP 接口时，请自行传入该字段。

图生视频

首帧与首尾帧

需要严格保持首帧或首尾帧一致时，使用 first_frame 和 last_frame。该模式不与 reference_* 多模态素材混用。

POST/v1/video-tasks

{
  "prompt": "镜头从室内平稳移动到窗外夜景",
  "inputs": [
    {"asset_id": "首帧素材 ID", "role": "first_frame"},
    {"asset_id": "尾帧素材 ID", "role": "last_frame"}
  ]
}

接口参考

素材

请求基地址为 https://api.gate.ayshq.com。以下接口均需要 Authorization: Bearer <API Token>；文档中的路径需要拼接到该基地址后调用。文件直传完成后，平台自动完成媒体与素材校验；调用方只需查询素材状态。

POST/v1/assets/upload-requests

申请本地文件的临时直传地址。

请求 JSON

字段类型必填说明

media_typestring是IMAGE、VIDEO 或 AUDIO

content_typestring是文件 MIME 类型，如 image/png

sizeinteger是文件字节数，必须准确

notestring否素材备注，最多 200 字符

{
  "media_type": "IMAGE",
  "content_type": "image/png",
  "size": 245812,
  "note": "产品正面参考图"
}

返回 200

{
  "asset_id": "0e7fe1c0-cf4a-4bb0-b2bc-e8ef0fc9ce2e",
  "upload_url": "https://storage.example.com/signed-upload-url",
  "expires_at": "2026-07-26T03:15:00Z",
  "status": "PENDING_UPLOAD"
}

PUT{upload_url}

使用上一步返回的完整 URL 直传文件。该请求发往存储服务，不携带 Seed Video 的 Authorization。

请求头

字段类型必填说明

Content-Typestring是必须与申请上传地址时一致

请求体binary是完整文件二进制内容

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @reference.png

后续状态

存储服务返回 HTTP 2xx 后，使用 GET /v1/assets/{asset_id} 查询。PENDING_UPLOAD 表示平台仍在校验，READY 表示素材已可用于创建任务，FAILED 时读取 error_message。

POST/v1/assets/url-imports

让平台从公开 URL 下载并校验素材，适合已有公网图片、视频或音频地址的场景。

请求 JSON

字段类型必填说明

source_urlstring是公开 HTTP(S) 地址，最大 100 MB

media_typestring是IMAGE、VIDEO 或 AUDIO

notestring否素材备注，最多 200 字符

{
  "source_url": "https://example.com/reference.mp4",
  "media_type": "VIDEO",
  "note": "动作参考"
}

返回 200

返回与素材详情相同的对象，成功时 status 为 READY，并包含短期有效的 preview_url。

GET/v1/assets

查询当前用户的素材列表，按创建时间倒序返回。

返回 200

[
  {
    "id": "0e7fe1c0-cf4a-4bb0-b2bc-e8ef0fc9ce2e",
    "media_type": "IMAGE",
    "status": "READY",
    "content_type": "image/png",
    "size": 245812,
    "width": 1280,
    "height": 720,
    "note": "产品正面参考图",
    "preview_url": "https://storage.example.com/signed-preview-url",
    "created_at": "2026-07-26T03:00:00Z"
  }
]

GET/v1/assets/{asset_id}

查询单个素材详情，返回字段与素材列表中的对象一致。

路径参数

字段类型必填说明

asset_idUUID是素材 ID

返回 200

返回素材对象，包含可播放/预览的短期 preview_url。

PATCH/v1/assets/{asset_id}

更新素材备注，不会改变素材文件本身。

请求 JSON

字段类型必填说明

notestring/null是最多 200 字符；传空字符串可清除备注

{"note": "片头产品参考图"}

返回 200

返回更新后的素材对象。

接口参考

视频任务

请求地址：https://api.gate.ayshq.com。例如创建任务的完整地址是 https://api.gate.ayshq.com/v1/video-tasks。
generate_audio 为可选布尔字段，默认 false。需要成片包含声音时传 true；使用 reference_audio 时也应传 true。参考音频用于引导生成的声音，不会被原样拼接到成片。
model_id + resolution 必须是当前账户已启用的精确组合，请先通过模型查询接口确认。

POST/v1/video-tasks

创建异步视频生成任务。建议每次传唯一的 Idempotency-Key。

请求头

字段类型必填说明

Idempotency-Keystring否最长 100 字符；相同键和相同请求返回原任务

请求 JSON

字段类型必填说明

promptstring条件最多 2000 字符；无素材时必填

model_idstring是指定生成模型；与 resolution 组成精确输出方案

resolutionstring是480p、720p、1080p、2k、4k；必须存在可用模型组合

aspect_ratiostring否16:9、9:16、1:1、4:3、3:4、21:9、adaptive

duration_secondsinteger否默认 4 秒；Seedance 2.5 模型支持 4–30 秒，其他模型支持 4–15 秒

generate_audioboolean否是否生成声音，默认 false

callback_urlstring否公网 HTTP(S) 回调地址；返回 Seed V1 任务查询格式

inputsarray条件已完成校验的素材；无 prompt 时必填，最多 9 个

inputs[].asset_idUUID是素材 ID

inputs[].rolestring是first_frame、last_frame、reference_image、reference_video 或 reference_audio

{
  "prompt": "清晨海面上的航拍镜头，阳光穿过薄雾",
  "model_id": "doubao-seedance-2-0-260128",
  "resolution": "480p",
  "aspect_ratio": "16:9",
  "duration_seconds": 4,
  "generate_audio": false,
  "callback_url": "https://client.example.com/seed-callback",
  "inputs": []
}

指定模型

创建任务必须填写模型；请先查询当前账户可用的 model_id + resolution 组合。

{
  "prompt": "清晨海面上的航拍镜头，阳光穿过薄雾",
  "model_id": "doubao-seedance-2-5-260628",
  "resolution": "480p",
  "duration_seconds": 4
}

返回 202

{
  "id": "a248ba24-f8a8-4f80-af8c-2da9cb64f615",
  "status": "queued",
  "created_at": "2026-07-26T03:10:00Z",
  "updated_at": "2026-07-26T03:10:00Z"
}

POSTSeed V1 callback_url

/v1/video-tasks 创建任务时传入公网回调地址。回调正文与 GET /v1/video-tasks/{task_id} 完全一致，状态为 queued、processing、succeeded 或 failed。

成功回调

POST https://client.example.com/seed-callback
Content-Type: application/json
X-Seed-Callback-Event-Id: 67b0d06d-...
X-Seed-Task-Id: a248ba24-...

{
  "id": "a248ba24-f8a8-4f80-af8c-2da9cb64f615",
  "status": "succeeded",
  "output_url": "https://storage.example.com/signed-output-url",
  "created_at": "2026-08-21T03:10:00Z",
  "updated_at": "2026-08-21T03:15:30Z",
  "completed_at": "2026-08-21T03:15:30Z"
}

回调地址不能是内网、本机或携带 URL 凭证的地址。接收端应在 5 秒内返回 2xx；终态失败后最多再重试 3 次，间隔 5 秒。请用 X-Seed-Callback-Event-Id 幂等去重。回调失败不影响任务和余额结算。

GET/v1/video-tasks/{task_id}

查询任务状态。建议在 queued 或 processing 时每 5 至 10 秒轮询。

路径参数

字段类型必填说明

task_idUUID是创建任务返回的任务 ID

处理中返回 200

{
  "id": "a248ba24-f8a8-4f80-af8c-2da9cb64f615",
  "status": "processing",
  "created_at": "2026-07-26T03:10:00Z",
  "updated_at": "2026-07-26T03:11:20Z"
}

成功返回 200

{
  "id": "a248ba24-f8a8-4f80-af8c-2da9cb64f615",
  "status": "succeeded",
  "output_url": "https://storage.example.com/signed-output-url",
  "created_at": "2026-07-26T03:10:00Z",
  "updated_at": "2026-07-26T03:15:30Z",
  "completed_at": "2026-07-26T03:15:30Z"
}

失败返回 200

{
  "id": "a248ba24-f8a8-4f80-af8c-2da9cb64f615",
  "status": "failed",
  "error": {"code": 50010, "error": "VIDEO_PROCESSING_FAILED", "message": "Video processing did not complete"},
  "completed_at": "2026-07-26T03:12:00Z"
}

GET/v1/video-tasks

分页查询当前用户的任务列表。

查询参数

字段类型默认说明

statusstringallall、queued、processing、succeeded、failed

pageinteger0从 0 开始的页码

sizeinteger20每页 1 至 100 条

返回 200

{
  "items": [{
    "id": "a248ba24-f8a8-4f80-af8c-2da9cb64f615",
    "status": "succeeded",
    "output_url": "https://storage.example.com/signed-output-url",
    "created_at": "2026-07-26T03:10:00Z",
    "updated_at": "2026-07-26T03:15:30Z",
    "completed_at": "2026-07-26T03:15:30Z"
  }],
  "total": 1,
  "page": 0,
  "size": 20
}

GET/v1/video-models

按模型分组返回当前账户支持的全部分辨率。

[{"model_id":"doubao-seedance-2-0-260128","resolutions":["480p","720p","1080p"]}]

协议兼容

火山 Seedance 兼容接口

如果你的系统已经按火山官方协议开发，可以直接使用下面这套接口。它与本页的 /v1/... 业务接口并行，二者请求格式互不影响。请求基地址仍然是 https://api.gate.ayshq.com。

模型与时长：model 与 resolution 均为必填，必须使用 GET /v1/video-models 返回的精确模型 ID 与分辨率组合。doubao-seedance-2.0 与 doubao-seedance-2-0-260128 不是通用别名。duration 默认 4 秒。Seedance 2.5 模型支持 4–30 秒，其他模型支持 4–15 秒；平台会按实际指定模型校验。

POST/api/v3/contents/generations/tasks

创建视频生成任务。支持 text、image_url、video_url、audio_url 内容类型；公网素材 URL 会由平台导入并校验。

请求 JSON

{
  "model": "doubao-seedance-2-0-260128",
  "content": [{"type": "text", "text": "一只猫在窗边"}],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 4,
  "generate_audio": true,
  "callback_url": "https://client.example.com/video-callback"
}

返回 200

{"id":"a248ba24-f8a8-4f80-af8c-2da9cb64f615","model":"doubao-seedance-2-0-260128","status":"queued","created_at":"2026-08-18T03:10:00Z"}

POSTcallback_url

创建任务时传入公网 HTTP(S) 回调地址。平台会在整体状态变为 queued、running、succeeded、failed 或 expired 时发送 JSON，正文与任务查询响应一致。取消任务使用 failed 状态并在 error.code 中返回 CANCELLED。

回调请求

POST https://client.example.com/video-callback
Content-Type: application/json
X-Seed-Callback-Event-Id: 67b0d06d-...
X-Seed-Task-Id: a248ba24-...

{
  "id": "a248ba24-f8a8-4f80-af8c-2da9cb64f615",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {"video_url": "https://storage.example.com/video.mp4"},
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 4,
  "generate_audio": true
}

接收端应在 5 秒内返回任意 2xx。终态首次失败后最多再重试 3 次，间隔 5 秒；同一事件可能重复投递，请使用 X-Seed-Callback-Event-Id 幂等去重。内网、本机、携带 URL 凭证或片段的地址会被拒绝。

GET/api/v3/contents/generations/tasks/{task_id}

查询任务。状态为 queued、running、succeeded、failed 或 expired；成功时从 content.video_url 读取成片地址。

{"id":"a248ba24-f8a8-4f80-af8c-2da9cb64f615","status":"succeeded","content":{"video_url":"https://storage.example.com/video.mp4"}}

GET/api/v3/contents/generations/tasks

分页查询任务。参数：page_num（从 1 开始，默认 1）、page_size（1 至 100，默认 20）、status。

{"data":[],"total":0,"page_num":1,"page_size":20}

DELETE/api/v3/contents/generations/tasks/{task_id}

取消尚未完成的任务。成功返回 HTTP 204。

POST真人/虚拟素材

本页接口完整兼容火山素材库协议。普通虚拟素材走 CreateAssetGroup → CreateAsset；真人素材必须先完成 CreateVisualValidateSession → GetVisualValidateResult。平台返回自己的 Group-* 和 Asset-*，内部完成上游 ID 映射，客户不会接触上游原始素材 ID。

鉴权说明

平台同时兼容火山官方素材库的 AK/SK HMAC 请求。客户在用户控制台创建一枚 API Token 后，将同一枚完整 Token 同时填写为官方 SDK 的 Access Key ID（AK）和 Secret Access Key（SK），请求根地址使用 https://api.gate.ayshq.com/：

AK = sk_live_xxx
SK = sk_live_xxx
Region = cn-beijing
Service = ark
Version = 2024-01-01

官方 SDK 生成的素材请求可以直接发送到平台根路径，也兼容 K23 风格的 /seedance/assets/ 路径。

素材库 Action 的完整请求形式为：

POST https://api.gate.ayshq.com/?Action=CreateAssetGroup&Version=2024-01-01
Authorization: HMAC-SHA256 Credential=sk_live_xxx/20260831/cn-beijing/ark/request, ...
X-Date: 20260831T120000Z
X-Content-Sha256: <请求体 SHA-256>

支持 CreateAssetGroup、GetAssetGroup、UpdateAssetGroup、DeleteAssetGroup、ListAssetGroups、CreateAsset、GetAsset、UpdateAsset、ListAssets、DeleteAsset、CreateVisualValidateSession 和 GetVisualValidateResult。

真人步骤 1：创建认证 H5

POST ?Action=CreateVisualValidateSession&Version=2024-01-01
{
  "CallbackURL": "https://client.example.com/liveness-result",
  "ProjectName": "default"
}

返回：
{
  "BytedToken": "validation-token",
  "H5Link": "https://ark.volcengine.com/...",
  "CallbackURL": "https://client.example.com/liveness-result"
}

终端用户打开 H5Link 完成本人认证。回调中的 resultCode=10000 表示认证成功。

真人步骤 2：取得平台素材组

POST ?Action=GetVisualValidateResult&Version=2024-01-01
{"BytedToken":"validation-token","ProjectName":"default"}

返回：{"GroupId":"Group-平台素材组ID"}

真人步骤 3：上传并等待素材可用

POST ?Action=CreateAsset&Version=2024-01-01
{
  "GroupId": "Group-平台素材组ID",
  "URL": "https://client.example.com/person.jpg",
  "Name": "已授权真人主播",
  "AssetType": "Image",
  "ProjectName": "default"
}

返回中的 Id 为 Asset-平台素材ID。

使用 GetAsset 轮询，只有 Status=Active 才能生成。视频请求中使用 asset://Asset-平台素材ID；平台会在提交上游前自动替换成对应的上游素材 ID。

在线调用

API Playground

填写 API Key 后可直接创建一条测试任务；生成的代码使用环境变量，不会显示或保存当前 Key。

下载 OpenAPI 3.0 规范

请求体JSON

生成代码Key 使用环境变量

响应

尚未发送请求

错误处理

统一错误格式

{
  "code": 40001,
  "error": "VALIDATION_FAILED",
  "message": "At least one of prompt or inputs is required",
  "request_id": "client-request-000001"
}

请保存响应头或响应体中的 request_id，排查问题时提供给支持人员。任务本身的生成失败通过任务状态 failed 返回，不会表现为 HTTP 请求失败。

SDK

可运行示例

仓库中提供只依赖标准库的 Python 客户端，以及基于 JDK HttpClient 和 Jackson 的 Java 客户端。多模态示例已覆盖本页全部七种组合。

下载 Python SDK Python 3.9+，无第三方依赖 下载 Java SDK JDK 17+，Maven 工程

压缩包不包含 Token。解压后按照包内 README 设置 SEED_API_TOKEN 和 SEED_API_BASE_URL，即可运行示例。

视频生成业务接口

最近更新

模型分组查询与在线调用

人民币余额计费

两套任务回调格式

模型与分辨率组合

只需三个业务步骤

创建 Token

提交任务

轮询并下载

请求参数

返回 200

素材上传对业务方是一项操作

七种多模态组合

首帧与首尾帧

素材

请求 JSON

返回 200

请求头

后续状态

请求 JSON

返回 200

返回 200

路径参数

返回 200

请求 JSON

返回 200

视频任务

请求头

请求 JSON

指定模型

返回 202

成功回调

路径参数

处理中返回 200

成功返回 200

失败返回 200

查询参数

返回 200

火山 Seedance 兼容接口

请求 JSON

返回 200

回调请求

鉴权说明

真人步骤 1：创建认证 H5

真人步骤 2：取得平台素材组

真人步骤 3：上传并等待素材可用

API Playground

统一错误格式

可运行示例