Open Move Seedance 视频生成 API 完整使用指南

本文介绍如何通过 Open Move 完成 Seedance 素材上传、素材查询、视频生成、任务查询和资源清理，并提供完整的真人人像认证与视频生成流程。

1. 接入信息

1.1 基础 URL

https://api.openmove.cn

1.2 鉴权方式

Seedance 接口使用两种鉴权方式：

接口类型	鉴权方式	凭证
视频生成、视频任务查询	Bearer Token	Open Move API Key
素材、素材组、真人活体认证	火山 V4 签名	Open Move 令牌对应的 Access Key ID 和 Secret Access Key

视频接口的鉴权请求头如下：

素材和真人认证接口共用以下地址，通过 Action 区分具体操作：

https://api.openmove.cn/openapi/volcengine/?Action={Action}&Version=2024-01-01

推荐使用 POST 和 JSON 请求体。V4 签名固定参数如下：

参数	值
Region	`cn-beijing`
Service	`ark`
Version	`2024-01-01`

V4 签名接口的通用请求头如下：

请求头	必填	说明
`Host`	是	固定为 `api.openmove.cn`
`Content-Type`	是	`application/json`
`X-Date`	是	UTC 时间，格式为 `yyyyMMddTHHmmssZ`，与服务端时间误差不得超过 15 分钟
`X-Content-Sha256`	是	实际发送请求体的 SHA256 小写十六进制哈希
`Authorization`	是	V4 签名结果，格式见下方示例

签名必须使用最终实际发送的请求方法、路径、查询字符串、请求头和请求体计算。请求体完成签名后不可再次序列化或修改。

1.3 火山 V4 签名算法

本节给出调用素材与真人认证接口所需的完整 V4 签名方法。若使用第 1.4 节中支持自定义路径的火山官方 SDK 或 Signer，可由其完成这些计算；自行发送 HTTP 请求时必须严格遵循本节。

1.3.1 签名固定配置

配置项	值
算法	`HMAC-SHA256`
Host	`api.openmove.cn`
Region	`cn-beijing`
Service	`ark`
API Version	`2024-01-01`
请求方法	推荐 `POST`
Canonical URI	`/openapi/volcengine/`
Signed Headers	`host;x-content-sha256;x-date`

以下内容以上传素材为例：

POST https://api.openmove.cn/openapi/volcengine/?Action=CreateAsset&Version=2024-01-01

1.3.2 第一步：生成请求体和 Payload Hash

请求体必须先完成最终 JSON 序列化，再计算 SHA256。哈希输入是实际发送的 UTF-8 字节，不是 JSON 对象、格式化前的字符串或字段值集合。

请求体示例：

{
  "GroupId": "group-20260727143000-aigc001",
  "URL": "https://cdn.example.com/materials/city-night.jpg",
  "AssetType": "Image",
  "Name": "城市夜景参考图",
  "ProjectName": "default"
}

伪代码：

PayloadHash = LowercaseHex(SHA256(RequestBodyUTF8Bytes))

将结果放入请求头：

空请求体的 SHA256 固定为：

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

1.3.3 第二步：生成 X-Date

使用当前 UTC 时间，精确到秒：

YYYYMMDD'T'HHMMSS'Z'

示例：

日期部分 20260727 后续用于 Credential Scope。请求时间与服务端时间误差不得超过 15 分钟。

1.3.4 第三步：构造 Canonical Query String

查询参数需要按以下规则规范化：

参数名和参数值使用 UTF-8，并按 RFC 3986 编码。

空格编码为 %20，不能编码为 +。

编码后的参数名按 ASCII 升序排列；同名参数的值也按升序排列。

使用 = 连接名称和值，使用 & 连接多个参数。

本接口的规范查询字符串为：

Action=CreateAsset&Version=2024-01-01

1.3.5 第四步：构造 Canonical Headers 和 Signed Headers

参与签名的请求头名称转为小写，按 ASCII 升序排列；值去掉首尾空格并压缩连续空白。每个 Canonical Header 末尾必须带换行符。

host:api.openmove.cn
x-content-sha256:<PayloadHash>
x-date:20260727T070000Z

Signed Headers 为同一组请求头名称，顺序必须完全一致：

host;x-content-sha256;x-date

Content-Type 必须随 POST 请求发送，但本指南不将其加入 Signed Headers。

1.3.6 第五步：构造 Canonical Request

按照以下顺序拼接，各部分之间使用一个换行符：

CanonicalRequest =
    HTTPMethod + "\n" +
    CanonicalURI + "\n" +
    CanonicalQueryString + "\n" +
    CanonicalHeaders + "\n" +
    SignedHeaders + "\n" +
    PayloadHash

上传素材请求对应的结构如下。注意 Canonical Headers 自身以换行符结束，因此其后会自然出现一个空行：

POST
/openapi/volcengine/
Action=CreateAsset&Version=2024-01-01
host:api.openmove.cn
x-content-sha256:<PayloadHash>
x-date:20260727T070000Z

host;x-content-sha256;x-date
<PayloadHash>

计算 Canonical Request 的 SHA256：

HashedCanonicalRequest = LowercaseHex(SHA256(UTF8(CanonicalRequest)))

1.3.7 第六步：构造 String to Sign

Credential Scope 格式如下：

<YYYYMMDD>/cn-beijing/ark/request

示例：

20260727/cn-beijing/ark/request

待签名字符串为：

StringToSign =
    "HMAC-SHA256" + "\n" +
    XDate + "\n" +
    CredentialScope + "\n" +
    HashedCanonicalRequest

结构示例：

HMAC-SHA256
20260727T070000Z
20260727/cn-beijing/ark/request
<HashedCanonicalRequest>

1.3.8 第七步：派生签名密钥并计算 Signature

所有 HMAC 操作均使用 HMAC-SHA256。每一步的输出必须以原始二进制字节作为下一步的密钥，不要先转换成十六进制字符串。

kDate    = HMAC-SHA256(UTF8(SecretAccessKey), "20260727")
kRegion  = HMAC-SHA256(kDate, "cn-beijing")
kService = HMAC-SHA256(kRegion, "ark")
kSigning = HMAC-SHA256(kService, "request")

Signature = LowercaseHex(HMAC-SHA256(kSigning, StringToSign))

1.3.9 第八步：构造 Authorization 并发送请求

Authorization =
    "HMAC-SHA256 " +
    "Credential=" + AccessKeyId + "/" + CredentialScope + ", " +
    "SignedHeaders=host;x-content-sha256;x-date, " +
    "Signature=" + Signature

最终请求结构：

1.3.10 可直接使用的 Python 手动签名示例

以下示例不依赖火山 SDK，仅需安装 requests。它会完成 JSON 序列化、V4 签名并调用 CreateAsset：

1.4 使用火山官方 SDK

支持自定义路径的火山官方 SDK 或 Signer 可以自动生成 V4 签名。接入 Open Move 时必须使用以下配置：

配置项	值
Access Key ID	Open Move 令牌对应的 Access Key ID
Secret Access Key	Open Move 令牌对应的 Secret Access Key
Region	`cn-beijing`
Service	`ark`
Version	`2024-01-01`
Endpoint Host	`api.openmove.cn`
Endpoint Path	`/openapi/volcengine/`

不同语言 SDK 对自定义路径的支持并不一致，请按下表选择接入方式，不要把 /openapi/volcengine 直接拼进只接受域名的 host 配置项：

语言	推荐方式	路径配置
Go	`volcengine-go-sdk` Universal Client	Endpoint 设为 `https://api.openmove.cn/openapi/volcengine`
Python	`volcengine` SDK 的 `SignerV4`	`host` 设为 `api.openmove.cn`，`path` 设为 `/openapi/volcengine/`
Java	标准 HTTP Client + 本文 V4 签名实现	当前 Universal SDK 将 Canonical URI 固定为 `/`，不能直接用于本接口路径
Node.js	`@volcengine/openapi` 的 `Signer`	`hostname` 设为 `api.openmove.cn`，`pathname` 设为 `/openapi/volcengine/`

建议通过环境变量保存凭证：

1.4.1 Go SDK

安装：

上传素材示例：

其他 Action 只需替换 Action 和 input。例如查询素材使用 Action: "GetAsset" 和 input := map[string]any{"Id": assetID}。

1.4.2 Python SDK

安装：

Python Universal Client 会把 configuration.host 整体作为 Host 参与签名，因此不能把 /openapi/volcengine 拼入 configuration.host。下面使用火山官方 Python SDK 的 SignerV4，分别设置域名和路径。

上传素材示例：

1.4.3 Java

当前火山 Java Universal SDK 的 Canonical URI 固定为 /，而 Open Move 要求签名路径为 /openapi/volcengine/，因此不能通过把路径拼入 setEndpoint 来适配。Java 项目应直接使用本文 1.3 节的标准 V4 算法。下面示例仅依赖 JDK 11+，可直接上传素材：

1.4.4 Node.js SDK

Node.js 示例使用火山官方 SDK 的 Signer，显式指定 Open Move 的完整路径，再通过 Node.js 原生 HTTPS 客户端发送请求。

安装：

上传素材示例：

1.5 素材与真人认证接口的通用响应

成功响应使用火山兼容格式：

{
  "ResponseMetadata": {
    "RequestId": "20260727150000ABCDEF1234567890",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {}
}

通用响应字段如下：

字段	类型	说明
`ResponseMetadata.RequestId`	string	请求 ID，可用于问题排查
`ResponseMetadata.Action`	string	本次执行的 Action
`ResponseMetadata.Version`	string	API 版本
`ResponseMetadata.Service`	string	固定为 `ark`
`ResponseMetadata.Region`	string	固定为 `cn-beijing`
`ResponseMetadata.Error`	object	失败时返回的错误信息
`ResponseMetadata.Error.Code`	string	错误码
`ResponseMetadata.Error.Message`	string	错误说明
`Result`	object	接口成功结果，不同 Action 的字段不同

错误响应示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727150000ABCDEF1234567890",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "ResourceNotFound",
      "Message": "the requested resource was not found"
    }
  }
}

调用方应同时检查 HTTP 状态码和 ResponseMetadata.Error。

2. 基础模块：使用普通素材生成视频

完整流程如下：

上传素材，取得素材 ID。

查询素材，等待处理成功。

使用素材 ID 创建视频生成任务，取得任务 ID。

查询任务，等待视频生成成功并获取视频地址。

删除不再使用的素材。

开始前请准备一个由 Open Move 服务方提供的普通素材组 ID（GroupId）。上传素材时，ProjectName 使用默认值 default；后续查询和删除素材时不传该字段。

步骤一：上传素材

该接口通过公网 URL 导入图片、视频或音频，不使用 multipart/form-data 直接上传文件。URL 必须是火山服务端可以直接访问的公网 URL：无需登录、Cookie 或额外鉴权请求头即可下载；若使用带签名的临时 URL，其有效期必须覆盖素材下载和处理时间。素材处理是异步的，接口返回素材 ID 后必须继续查询处理状态。

接口地址

https://api.openmove.cn/openapi/volcengine/?Action=CreateAsset&Version=2024-01-01

请求方式

POST

请求头

使用第 1.2 节所述的 V4 签名请求头。

请求体

参数	类型	必填	说明
`URL`	string	是	火山服务端可直接访问的素材公网 URL
`AssetType`	string	是	素材类型：`Image`、`Video` 或 `Audio`
`Name`	string	否	素材名称
`GroupId`	string	是	Open Move 服务方提供的普通素材组 ID
`ProjectName`	string	否	项目名称，默认值为 `default`

请求体示例：

{
  "GroupId": "group-20260727143000-aigc001",
  "URL": "https://cdn.example.com/materials/city-night.jpg",
  "AssetType": "Image",
  "Name": "城市夜景参考图",
  "ProjectName": "default"
}

响应体

除通用响应字段外，Result 包含：

字段	类型	说明
`Result.Id`	string	素材 ID，后续查询素材和生成视频时使用

响应体示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727150001ABCDEF1234567890",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260727150001-a1b2c3"
  }
}

请保存 Result.Id。

步骤二：查询素材并等待处理成功

建议每 5 秒查询一次，直到素材进入成功或失败终态。不同上游可能返回不同大小写，调用方应不区分大小写判断状态。

接口地址

https://api.openmove.cn/openapi/volcengine/?Action=GetAsset&Version=2024-01-01

请求方式

POST

请求头

使用 V4 签名请求头。

请求体

参数	类型	必填	说明
`Id`	string	是	`CreateAsset` 返回的素材 ID

请求体示例：

{
  "Id": "asset-20260727150001-a1b2c3"
}

响应体

Result 字段如下：

字段	类型	说明
`Id`	string	素材 ID
`Name`	string	素材名称
`GroupId`	string	素材所属的素材组 ID
`AssetType`	string	`Image`、`Video` 或 `Audio`
`Status`	string	素材处理状态
`URL`	string	处理后的临时素材地址；可能带签名并具有有效期
`ProjectName`	string	默认值为 `default`
`CreateTime`	string	创建时间
`UpdateTime`	string	更新时间

常见状态如下：

状态	含义	后续操作
`Processing`	正在处理	继续轮询
`Active`、`Ready`、`READY`	处理成功，素材可用	停止轮询并创建视频任务
`Failed`	处理失败	停止轮询，检查素材 URL、格式或上游错误

处理中响应示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727150006ABCDEF1234567890",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260727150001-a1b2c3",
    "Name": "城市夜景参考图",
    "GroupId": "group-20260727143000-aigc001",
    "AssetType": "Image",
    "Status": "Processing",
    "ProjectName": "default"
  }
}

处理成功响应示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727150016ABCDEF1234567890",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260727150001-a1b2c3",
    "Name": "城市夜景参考图",
    "GroupId": "group-20260727143000-aigc001",
    "AssetType": "Image",
    "Status": "Active",
    "URL": "https://ark-media.example.com/assets/a1b2c3?signature=...",
    "ProjectName": "default",
    "CreateTime": "2026-07-27T15:00:01+08:00",
    "UpdateTime": "2026-07-27T15:00:16+08:00"
  }
}

步骤三：使用素材 ID 生成视频

素材处理成功后，在 content 中使用 asset://{素材 ID} 引用素材。图片、视频和音频素材应分别放在 image_url、video_url 和 audio_url 字段中。

接口地址

https://api.openmove.cn/api/v3/contents/generations/tasks

请求方式

POST

请求头

请求头	必填	说明
`Authorization`	是	`Bearer <OPEN_MOVE_API_KEY>`
`Content-Type`	是	`application/json`

请求体

参数	类型	必填	说明
`model`	string	是	Seedance 模型 ID，例如 `doubao-seedance-2-0-260128`；以控制台可用模型为准
`content`	array	与 `prompt` 二选一	文本和素材输入数组
`content[].type`	string	是	`text`、`image_url`、`video_url` 或 `audio_url`
`content[].text`	string	条件必填	`type=text` 时填写提示词
`content[].image_url.url`	string	条件必填	图片 URL 或 `asset://{图片素材 ID}`
`content[].video_url.url`	string	条件必填	视频 URL 或 `asset://{视频素材 ID}`
`content[].audio_url.url`	string	条件必填	音频 URL 或 `asset://{音频素材 ID}`
`content[].role`	string	否	`first_frame`、`last_frame`、`reference_image`、`reference_video` 或 `reference_audio`
`prompt`	string	否	简写提示词；与 `content` 二选一
`images`	string[]	否	与 `prompt` 搭配使用的图片 URL 或 `asset://` 引用数组
`resolution`	string	否	例如 `480p`、`720p`、`1080p`
`ratio`	string	否	例如 `16:9`、`9:16`、`1:1`、`adaptive`
`duration`	integer	否	视频时长，单位为秒；支持范围由模型决定
`frames`	integer	否	视频总帧数；通常与 `duration` 二选一
`seed`	integer	否	随机种子；`-1` 通常表示随机
`camera_fixed`	boolean	否	是否固定镜头
`watermark`	boolean	否	是否添加水印
`generate_audio`	boolean	否	是否生成音频，仅部分模型支持
`return_last_frame`	boolean	否	是否在结果中返回尾帧图片
`draft`	boolean	否	是否使用草稿模式，仅部分模型支持
`service_tier`	string	否	服务等级，例如 `default`
`execution_expires_after`	integer	否	任务执行超时时间，单位为秒
`callback_url`	string	否	任务状态回调地址
`tools`	array	否	模型支持的扩展工具配置

请求体示例：

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-20260727150001-a1b2c3"
      },
      "role": "reference_image"
    },
    {
      "type": "text",
      "text": "夜晚的城市街道逐渐被霓虹灯点亮，镜头平稳向前推进，电影感光影"
    }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": false
}

响应体

字段	类型	说明
`id`	string	视频生成任务 ID，用于查询任务状态

响应体示例：

{
  "id": "cgt-20260727150100-video123"
}

请保存 id。该接口为异步接口，返回任务 ID 不代表视频已经生成完成。

步骤四：通过任务 ID 查询视频任务

建议以固定间隔轮询，直到 status 为 succeeded 或 failed。

接口地址

https://api.openmove.cn/api/v3/contents/generations/tasks/{task_id}

请求方式

GET

请求头

请求头	必填	说明
`Authorization`	是	`Bearer <OPEN_MOVE_API_KEY>`

请求体

无请求体。

路径参数如下：

参数	类型	必填	说明
`task_id`	string	是	创建视频任务时返回的 `id`

请求示例：

响应体

字段	类型	说明
`id`	string	任务 ID
`model`	string	实际使用的模型 ID
`status`	string	`queued`、`running`、`succeeded` 或 `failed`
`content.video_url`	string	成功时返回的视频临时下载地址
`content.last_frame_url`	string	请求返回尾帧时可能出现的尾帧图片地址
`usage.completion_tokens`	integer	生成消耗的 token 数
`usage.total_tokens`	integer	总 token 数
`error.code`	string	失败时的错误码
`error.message`	string	失败原因
`created_at`	integer	创建时间，Unix 秒
`updated_at`	integer	更新时间，Unix 秒

处理中响应示例：

{
  "id": "cgt-20260727150100-video123",
  "model": "doubao-seedance-2-0-260128",
  "status": "running",
  "created_at": 1785135660,
  "updated_at": 1785135680
}

生成成功响应示例：

{
  "id": "cgt-20260727150100-video123",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://ark-content.example.com/videos/video123.mp4?signature=..."
  },
  "usage": {
    "completion_tokens": 135680,
    "total_tokens": 135680
  },
  "created_at": 1785135660,
  "updated_at": 1785135740
}

生成失败响应示例：

{
  "id": "cgt-20260727150100-video123",
  "model": "doubao-seedance-2-0-260128",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "video generation failed"
  },
  "created_at": 1785135660,
  "updated_at": 1785135700
}

video_url 通常是带签名的临时地址，请在有效期内下载并转存。

步骤五：删除素材

视频生成完成且不再需要素材时，可删除素材。

特别提示：该删除接口仅部分素材分组支持。 调用前请确认目标素材所在分组已开通删除能力；不支持删除的分组无法通过本接口清理素材。

接口地址

https://api.openmove.cn/openapi/volcengine/?Action=DeleteAsset&Version=2024-01-01

请求方式

POST

请求头

使用 V4 签名请求头。

请求体

参数	类型	必填	说明
`Id`	string	是	要删除的素材 ID

请求体示例：

{
  "Id": "asset-20260727150001-a1b2c3"
}

响应体

删除成功时只返回通用的 ResponseMetadata，不返回 Result。

字段	类型	说明
`ResponseMetadata`	object	删除请求已处理；子字段含义见第 1.5 节

响应体示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727150500ABCDEF1234567890",
    "Action": "DeleteAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  }
}

3. 真人人像模块

真人人像素材必须先完成活体认证。CreateAssetGroup 只能创建普通 AIGC 素材组，不能代替真人认证。真人素材组只能由活体认证成功后返回。

完整流程如下：

创建真人活体认证会话。

用户打开 H5 页面完成认证，调用查询接口取得真人素材组 ID。

使用真人素材组 ID 上传真人人像素材。

查询素材，等待处理成功。

使用真人人像素材 ID 生成视频。

查询视频任务，等待生成完成。

删除真人人像素材。

删除真人人像素材组。

步骤一：进行真人活体认证

该接口创建一个有效期为 30 分钟的 H5 活体认证会话。调用方需要保存 BytedToken，并让当前被认证用户在浏览器中打开 H5Link。

接口地址

https://api.openmove.cn/openapi/volcengine/?Action=CreateVisualValidateSession&Version=2024-01-01

请求方式

POST

请求头

使用 V4 签名请求头。

请求体

参数	类型	必填	说明
`CallbackURL`	string	是	认证流程结束后浏览器最终跳转的业务方地址，必须是调用方自己的页面

请求体示例：

{
  "CallbackURL": "https://your-app.example.com/seedance/verify/callback?user_id=10001"
}

响应体

Result 字段如下：

字段	类型	说明
`BytedToken`	string	认证会话令牌，查询认证结果时使用
`H5Link`	string	用户完成活体认证的 H5 页面地址
`CallbackURL`	string	回显调用方传入的回调地址

响应体示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727160000ABCDEF1234567890",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "BytedToken": "cv-token-20260727160000-abc123",
    "H5Link": "https://visual.volcengineapi.com/verify?token=cv-token-20260727160000-abc123",
    "CallbackURL": "https://your-app.example.com/seedance/verify/callback?user_id=10001"
  }
}

用户完成 H5 操作后，Open Move 会处理认证结果，再通过 HTTP 302 跳转到 CallbackURL。业务方原有查询参数会被保留，并可能收到 bytedToken、resultCode 和 groupId。浏览器跳转可能被用户关闭或网络中断，因此最终结果必须以查询接口为准。

步骤二：查询活体认证状态

用户打开 H5 页面后，建议每 3～5 秒查询一次。认证成功后返回的 GroupId 就是真人素材组 ID。

接口地址

https://api.openmove.cn/openapi/volcengine/?Action=GetVisualValidateResult&Version=2024-01-01

请求方式

POST

请求头

使用 V4 签名请求头。

请求体

参数	类型	必填	说明
`BytedToken`	string	是	创建认证会话时返回的 `BytedToken`

请求体示例：

{
  "BytedToken": "cv-token-20260727160000-abc123"
}

响应体

字段	类型	说明
`Result.GroupId`	string	认证成功后创建的 `LivenessFace` 真人素材组 ID

认证成功响应示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727160020ABCDEF1234567890",
    "Action": "GetVisualValidateResult",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "GroupId": "group-20260727160020-livenessface-xyz"
  }
}

认证尚未完成时，接口可能返回空 Result，也可能在 ResponseMetadata.Error.Code 中返回上游的等待状态，例如 ValidatePending。此时继续轮询；返回非空 GroupId 时停止轮询。会话超过 30 分钟仍未成功时，应重新创建认证会话。

步骤三：上传真人人像到真人素材库

真人素材上传仍使用 CreateAsset，并传入上一步认证成功后返回的 GroupId。

接口地址

https://api.openmove.cn/openapi/volcengine/?Action=CreateAsset&Version=2024-01-01

请求方式

POST

请求头

使用 V4 签名请求头。

请求体

参数	类型	必填	说明
`GroupId`	string	是	`GetVisualValidateResult` 返回的真人素材组 ID
`URL`	string	是	火山服务端可直接访问的真人图片或视频公网 URL；不得依赖 Cookie 或额外鉴权请求头
`AssetType`	string	是	通常为 `Image` 或 `Video`；支持值为 `Image`、`Video`、`Audio`
`Name`	string	否	真人素材名称

请求体示例：

{
  "GroupId": "group-20260727160020-livenessface-xyz",
  "URL": "https://cdn.example.com/people/person-10001.mp4",
  "AssetType": "Video",
  "Name": "用户 10001 真人参考视频"
}

响应体

字段	类型	说明
`Result.Id`	string	真人人像素材 ID

响应体示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727160100ABCDEF1234567890",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260727160100-person001"
  }
}

步骤四：查询真人人像素材上传状态

轮询 GetAsset，直到 Status 为 Active 或 READY 等成功状态。

接口地址

https://api.openmove.cn/openapi/volcengine/?Action=GetAsset&Version=2024-01-01

请求方式

POST

请求头

使用 V4 签名请求头。

请求体

参数	类型	必填	说明
`Id`	string	是	上传真人人像时返回的素材 ID

请求体示例：

{
  "Id": "asset-20260727160100-person001"
}

响应体

字段	类型	说明
`Id`	string	真人人像素材 ID
`Name`	string	素材名称
`GroupId`	string	所属真人素材组 ID
`AssetType`	string	素材类型
`Status`	string	`Processing`、`Active`、`READY` 或 `Failed` 等状态
`URL`	string	处理后的临时素材地址
`ProjectName`	string	默认值为 `default`
`CreateTime`	string	创建时间
`UpdateTime`	string	更新时间

处理成功响应示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727160120ABCDEF1234567890",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260727160100-person001",
    "Name": "用户 10001 真人参考视频",
    "GroupId": "group-20260727160020-livenessface-xyz",
    "AssetType": "Video",
    "Status": "Active",
    "URL": "https://ark-media.example.com/assets/person001?signature=...",
    "ProjectName": "default",
    "CreateTime": "2026-07-27T16:01:00+08:00",
    "UpdateTime": "2026-07-27T16:01:20+08:00"
  }
}

步骤五：使用真人人像素材 ID 生成视频

真人人像素材处理成功后，使用 asset://{素材 ID} 引用。下面以真人视频素材作为 reference_video 为例；若上传的是图片，则改用 image_url 和 reference_image。

接口地址

https://api.openmove.cn/api/v3/contents/generations/tasks

请求方式

POST

请求头

请求头	必填	说明
`Authorization`	是	`Bearer <OPEN_MOVE_API_KEY>`
`Content-Type`	是	`application/json`

请求体

参数	类型	必填	说明
`model`	string	是	Seedance 模型 ID
`content`	array	是	提示词与真人人像素材引用
`content[].type`	string	是	真人图片使用 `image_url`，真人视频使用 `video_url`
`content[].image_url.url`	string	条件必填	`asset://{真人图片素材 ID}`
`content[].video_url.url`	string	条件必填	`asset://{真人视频素材 ID}`
`content[].role`	string	建议填写	真人图片建议 `reference_image`，真人视频建议 `reference_video`
`content[].text`	string	是	视频内容和人物动作提示词
`resolution`	string	否	输出分辨率
`ratio`	string	否	输出画面比例
`duration`	integer	否	视频时长，单位为秒
`frames`	integer	否	视频总帧数；通常与 `duration` 二选一
`seed`	integer	否	随机种子；`-1` 通常表示随机
`camera_fixed`	boolean	否	是否固定镜头
`generate_audio`	boolean	否	是否生成音频，仅部分模型支持
`watermark`	boolean	否	是否添加水印
`return_last_frame`	boolean	否	是否在结果中返回尾帧图片
`draft`	boolean	否	是否使用草稿模式，仅部分模型支持
`service_tier`	string	否	服务等级，例如 `default`
`execution_expires_after`	integer	否	任务执行超时时间，单位为秒
`callback_url`	string	否	任务状态回调地址
`tools`	array	否	模型支持的扩展工具配置

请求体示例：

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "video_url",
      "video_url": {
        "url": "asset://asset-20260727160100-person001"
      },
      "role": "reference_video"
    },
    {
      "type": "text",
      "text": "保持人物身份特征一致，人物自然地走向镜头并微笑挥手，真实摄影风格，光线柔和"
    }
  ],
  "resolution": "1080p",
  "ratio": "9:16",
  "duration": 5,
  "generate_audio": false,
  "watermark": false
}

响应体

字段	类型	说明
`id`	string	视频生成任务 ID

响应体示例：

{
  "id": "cgt-20260727160200-person-video001"
}

步骤六：查询真人人像视频任务状态

接口地址

https://api.openmove.cn/api/v3/contents/generations/tasks/{task_id}

请求方式

GET

请求头

请求头	必填	说明
`Authorization`	是	`Bearer <OPEN_MOVE_API_KEY>`

请求体

无请求体。

路径参数	类型	必填	说明
`task_id`	string	是	上一步返回的视频任务 ID

请求示例：

响应体

字段	类型	说明
`id`	string	任务 ID
`model`	string	模型 ID
`status`	string	`queued`、`running`、`succeeded` 或 `failed`
`content.video_url`	string	生成成功后的视频临时下载地址
`content.last_frame_url`	string	可选的尾帧图片地址
`usage.completion_tokens`	integer	生成 token 数
`usage.total_tokens`	integer	总 token 数
`error.code`	string	失败错误码
`error.message`	string	失败说明
`created_at`	integer	创建时间，Unix 秒
`updated_at`	integer	更新时间，Unix 秒

成功响应示例：

{
  "id": "cgt-20260727160200-person-video001",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "content": {
    "video_url": "https://ark-content.example.com/videos/person-video001.mp4?signature=..."
  },
  "usage": {
    "completion_tokens": 135680,
    "total_tokens": 135680
  },
  "created_at": 1785139320,
  "updated_at": 1785139400
}

若 status 为 queued 或 running，继续轮询；若为 failed，读取 error.code 和 error.message 后停止轮询。

步骤七：删除真人人像素材

应先删除组内不再使用的真人人像素材，再删除真人素材组。

特别提示：该删除接口仅部分真人素材分组支持。 调用前请确认目标素材所在分组已开通删除能力；不支持删除的分组无法通过本接口清理素材。

接口地址

https://api.openmove.cn/openapi/volcengine/?Action=DeleteAsset&Version=2024-01-01

请求方式

POST

请求头

使用 V4 签名请求头。

请求体

参数	类型	必填	说明
`Id`	string	是	要删除的真人人像素材 ID

请求体示例：

{
  "Id": "asset-20260727160100-person001"
}

响应体

字段	类型	说明
`ResponseMetadata`	object	删除请求已处理；成功时不返回 `Result`，子字段含义见第 1.5 节

响应体示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727160500ABCDEF1234567890",
    "Action": "DeleteAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  }
}

步骤八：删除真人人像素材组

删除素材组会清理该组及其组内素材。该操作不可逆，执行前应确认组内素材和业务引用均已不再使用。

特别提示：该删除接口仅部分真人素材分组支持。 调用前请确认目标素材组已开通删除能力；不支持删除的分组无法通过本接口清理素材组。

接口地址

https://api.openmove.cn/openapi/volcengine/?Action=DeleteAssetGroup&Version=2024-01-01

请求方式

POST

请求头

使用 V4 签名请求头。

请求体

参数	类型	必填	说明
`Id`	string	是	要删除的真人素材组 ID，即认证成功后返回的 `GroupId`

请求体示例：

{
  "Id": "group-20260727160020-livenessface-xyz"
}

响应体

字段	类型	说明
`ResponseMetadata`	object	删除请求已处理；成功时不返回 `Result`，子字段含义见第 1.5 节

响应体示例：

{
  "ResponseMetadata": {
    "RequestId": "20260727160510ABCDEF1234567890",
    "Action": "DeleteAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  }
}

4. 轮询与资源管理建议

素材状态建议每 5 秒查询一次，并设置业务超时；成功状态应兼容 Active、Ready 和 READY。

活体认证建议每 3～5 秒查询一次，最长不超过会话的 30 分钟有效期。

视频任务建议根据业务并发设置合理轮询间隔，对 HTTP 429 和 5xx 使用退避重试。

URL、video_url 和 last_frame_url 可能是带签名的临时地址，应及时下载并转存。

使用同一 Open Move 账号创建、查询和删除素材；素材 ID、素材组 ID 和活体认证令牌均与创建它们的账号及上游实例绑定。

删除素材组前先停止相关生成任务并确认业务不再引用该组；删除真人素材组后，如需再次上传真人素材，必须重新完成活体认证。

Open Move Seedance 视频生成 API 完整使用指南

1. 接入信息#

1.1 基础 URL#

1.2 鉴权方式#

1.3 火山 V4 签名算法#

1.3.1 签名固定配置#

1.3.2 第一步：生成请求体和 Payload Hash#

1.3.3 第二步：生成 X-Date#

1.3.4 第三步：构造 Canonical Query String#

1.3.5 第四步：构造 Canonical Headers 和 Signed Headers#

1.3.6 第五步：构造 Canonical Request#

1.3.7 第六步：构造 String to Sign#

1.3.8 第七步：派生签名密钥并计算 Signature#

1.3.9 第八步：构造 Authorization 并发送请求#

1.3.10 可直接使用的 Python 手动签名示例#

1.4 使用火山官方 SDK#

1.4.1 Go SDK#

1.4.2 Python SDK#

1.4.3 Java#

1.4.4 Node.js SDK#

1.5 素材与真人认证接口的通用响应#

2. 基础模块：使用普通素材生成视频#

步骤一：上传素材#

接口地址#

请求方式#

请求头#

请求体#

响应体#

步骤二：查询素材并等待处理成功#

接口地址#

请求方式#

请求头#

请求体#

响应体#

步骤三：使用素材 ID 生成视频#

接口地址#

请求方式#

请求头#

请求体#

响应体#

步骤四：通过任务 ID 查询视频任务#

接口地址#

请求方式#

请求头#

请求体#

响应体#

步骤五：删除素材#

接口地址#

请求方式#

请求头#

请求体#

响应体#

3. 真人人像模块#

步骤一：进行真人活体认证#

接口地址#

请求方式#

请求头#

请求体#

响应体#

步骤二：查询活体认证状态#

接口地址#

请求方式#

请求头#

请求体#

响应体#

步骤三：上传真人人像到真人素材库#

接口地址#

请求方式#

请求头#

请求体#

响应体#

步骤四：查询真人人像素材上传状态#

接口地址#

请求方式#

请求头#

请求体#

响应体#

步骤五：使用真人人像素材 ID 生成视频#

接口地址#

请求方式#

1. 接入信息

1.1 基础 URL

1.2 鉴权方式

1.3 火山 V4 签名算法

1.3.1 签名固定配置

1.3.2 第一步：生成请求体和 Payload Hash

1.3.3 第二步：生成 X-Date

1.3.4 第三步：构造 Canonical Query String

1.3.5 第四步：构造 Canonical Headers 和 Signed Headers

1.3.6 第五步：构造 Canonical Request

1.3.7 第六步：构造 String to Sign

1.3.8 第七步：派生签名密钥并计算 Signature

1.3.9 第八步：构造 Authorization 并发送请求

1.3.10 可直接使用的 Python 手动签名示例

1.4 使用火山官方 SDK

1.4.1 Go SDK

1.4.2 Python SDK

1.4.3 Java

1.4.4 Node.js SDK

1.5 素材与真人认证接口的通用响应

2. 基础模块：使用普通素材生成视频

步骤一：上传素材

接口地址

请求方式

请求头

请求体

响应体

步骤二：查询素材并等待处理成功

接口地址

请求方式

请求头

请求体

响应体

步骤三：使用素材 ID 生成视频

接口地址

请求方式

请求头

请求体

响应体

步骤四：通过任务 ID 查询视频任务

接口地址

请求方式

请求头

请求体

响应体

步骤五：删除素材

接口地址

请求方式

请求头

请求体

响应体

3. 真人人像模块

步骤一：进行真人活体认证

接口地址

请求方式

请求头

请求体

响应体

步骤二：查询活体认证状态

接口地址

请求方式

请求头

请求体

响应体

步骤三：上传真人人像到真人素材库

接口地址

请求方式

请求头

请求体

响应体

步骤四：查询真人人像素材上传状态

接口地址

请求方式

请求头

请求体

响应体

步骤五：使用真人人像素材 ID 生成视频

接口地址

请求方式

请求头