OpenAPI 参考

Modelink API · 火山素材兼容接口

兼容火山方舟私域虚拟人像与真人人像素材协议。客户端可以保留火山协议的 Action、请求体、响应信封和 V4 签名逻辑，只需将 Base URL 与凭据替换为 Modelink 提供的值。调用 Action 前，先使用 Bearer API Key 查询可用的 ProjectName。

版本 1.0.0

调用火山素材 Action

POST

/volcengine/assets/

以火山方舟兼容协议管理私域人像素材。实际接口路径固定为 POST /volcengine/assets/（末尾斜杠不可省略），通过查询参数 Action 选择操作。

接入顺序

使用 Bearer API Key 调用 GET /v1/asset-projects，取得 cv1-xxxxx 格式的 ProjectName。
将同一个 Modelink API Key 同时作为 V4 Access Key 和签名密钥。
对最终 JSON 原始字节计算 SHA-256，将小写十六进制摘要写入 X-Content-Sha256。
X-Date 使用 UTC yyyyMMdd'T'HHmmss'Z'，服务端允许的时钟偏差为 5 分钟。
固定签名范围为 {date}/cn-beijing/ark/request，固定 SignedHeaders=content-type;host;x-content-sha256;x-date。

Authorization 格式：

HMAC-SHA256 Credential={api_key}/{yyyyMMdd}/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature={hex_signature}

Action 与请求体

Action	用途	请求体 schema
`CreateAssetGroup`	创建虚拟人像素材组	`CreateAssetGroupRequest`
`CreateAsset`	上传图片、视频或音频素材	`CreateAssetRequest`
`GetAssetGroup`	查询单个素材组	`GetAssetGroupRequest`
`ListAssetGroups`	查询素材组列表	`ListAssetGroupsRequest`
`UpdateAssetGroup`	更新素材组名称或描述	`UpdateAssetGroupRequest`
`DeleteAssetGroup`	删除素材组	`DeleteAssetGroupRequest`
`GetAsset`	查询单个素材及处理状态	`GetAssetRequest`
`ListAssets`	查询素材列表	`ListAssetsRequest`
`UpdateAsset`	更新素材名称	`UpdateAssetRequest`
`DeleteAsset`	删除素材	`DeleteAssetRequest`
`CreateVisualValidateSession`	创建真人人像认证会话	`CreateVisualValidateSessionRequest`
`GetVisualValidateResult`	查询真人认证结果与素材组 ID	`GetVisualValidateResultRequest`

请求体中的 ProjectName 均为必填，且必须使用项目查询接口返回的值。查询、更新或删除资源时，ProjectName 必须与创建资源时一致。创建与处理素材是异步过程；CreateAsset 返回 ID 后，应轮询 GetAsset，仅 Status=Active 的素材可用于视频生成。

认证方式

VolcengineV4AuthAPI 密钥

唯一的认证方式：火山 V4 HMAC-SHA256 签名。将同一个 Modelink API Key 同时用作 Credential 中的 Access Key 和签名密钥；签名范围固定为 cn-beijing/ark/request。X-Date 与 X-Content-Sha256 是参与签名并随请求发送的必需请求头，不是额外的认证方式。

完整请求必须包含以下三个 Header；三者须针对同一个最终 URL 与请求体生成，占位符不能固定复用：

Authorization: YOUR_VOLCENGINE_V4_AUTH
X-Date: YOUR_VOLCENGINE_V4_DATE
X-Content-Sha256: YOUR_VOLCENGINE_V4_PAYLOAD_HASH

header 参数：Authorization

查询参数

Name
Action
Type
enum, 必填
Description
要执行的火山素材操作。请求体必须与所选 Action 对应。
Name
Version
Type
"2024-01-01", 必填
Description
接口版本，固定为 2024-01-01。

请求头

Name
X-Date
Type
string, 必填
Description
V4 签名必需请求头。使用 UTC yyyyMMdd'T'HHmmss'Z' 格式；该值参与 Canonical Request 和 String to Sign，与服务端时间偏差不能超过 5 分钟。
Name
X-Content-Sha256
Type
string, 必填
Description
V4 签名必需请求头。对最终请求体原始字节计算 SHA-256，并发送其小写十六进制值；签名后不得重新序列化请求体。

请求体

根据 Action 选择对应的请求体。所有字段名与枚举值均区分大小写。

请求体属性

- Namestring, 必填
  素材组名称，最多 64 个字符。
- Descriptionstring
  素材组描述，最多 300 个字符。
- GroupType"AIGC"
  素材组类型。该 Action 仅创建虚拟人像组，固定为 AIGC；真人人像组由真人认证流程创建。
  const: AIGC; default: AIGC
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- - Image
  - Video
  - Audio
- GroupIdstring, 必填
  素材所属的素材组 ID。素材组必须属于同一 API Key 和 ProjectName。
- Namestring
  素材名称，最多 64 个字符；仅用于列表搜索，不会写入视频提示词。
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- URLstring<uri>, 必填
  素材的公网可访问 HTTP(S) URL。图片支持 jpeg、png、webp、bmp、tiff、gif、heic、heif；视频支持 mp4、mov；音频支持 wav、mp3。
  pattern: ^https?://
- Idstring, 必填
  素材组 ID 或素材 ID，由对应创建接口返回。
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- - GroupIdsstring[]
    限定素材组 ID 列表。
  - AIGC
    LivenessFace
  - Namestring
    按素材组名称搜索。
- PageNumberinteger<int64>, 必填
  页码，从 1 开始。
  minimum: 1
- PageSizeinteger<int64>, 必填
  每页数量，最大为 100。
  minimum: 1; maximum: 100
- - CreateTime
  - UpdateTime
- - Desc
  - Asc
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- Idstring, 必填
  要更新的素材组 ID。
- Namestring
  新的素材组名称，最多 64 个字符。
- Descriptionstring
  新的素材组描述，最多 300 个字符。
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- Idstring, 必填
  素材组 ID 或素材 ID，由对应创建接口返回。
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- Idstring, 必填
  素材组 ID 或素材 ID，由对应创建接口返回。
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- - GroupIdsstring[]
    限定素材所属的素材组 ID 列表。
  - AIGC
    LivenessFace
  - Processing
    Active
    Failed
  - Namestring
    按素材名称搜索。
- PageNumberinteger<int64>, 必填
  页码，从 1 开始。
  minimum: 1
- PageSizeinteger<int64>, 必填
  每页数量，最大为 100。
  minimum: 1; maximum: 100
- - CreateTime
  - UpdateTime
  - GroupId
- - Desc
  - Asc
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- Idstring, 必填
  要更新的素材 ID。
- Namestring, 必填
  新的素材名称，最多 64 个字符。
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- Idstring, 必填
  素材组 ID 或素材 ID，由对应创建接口返回。
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- CallbackURLstring<uri>, 必填
  真人认证完成后跳转的公网可访问 HTTP(S) URL，最多 500 个字符。回调查询参数中的 resultCode=10000 表示检测成功。
  pattern: ^https?://
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$
- BytedTokenstring, 必填
  真人认证唯一凭证，由 CreateVisualValidateSession 返回。凭证有效期为 30 分钟，仅支持完成一次认证，请勿写入公开日志。
- ProjectNamestring, 必填
  Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
  pattern: ^cv1-[0-9a-z]{5}$

请求

POST/volcengine/assets/

curl 'https://api.qnaigc.com/volcengine/assets/?Action={Action}&Version={Version}' \
  --request POST \
  --header 'Authorization: YOUR_VOLCENGINE_V4_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "Name": "品牌虚拟人像",
  "Description": "用于品牌宣传视频",
  "GroupType": "AIGC",
  "ProjectName": "cv1-bogic"
}'

响应

object

Action 调用成功。Result 的结构由 Action 决定。

响应体属性

- RequestIdstring, 必填
  本次请求的唯一标识，用于问题排查。
- - CreateAssetGroup
  - CreateAsset
  - GetAssetGroup
  - ListAssetGroups
  - UpdateAssetGroup
  - DeleteAssetGroup
  - GetAsset
  - ListAssets
  - UpdateAsset
  - DeleteAsset
  - CreateVisualValidateSession
  - GetVisualValidateResult
- Version"2024-01-01", 必填
  必填。
  const: 2024-01-01
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Idstring, 必填
    新建或已更新的素材组 ID / 素材 ID。
- - Idstring, 必填
    素材组 ID。
  - Namestring, 必填
    素材组名称。
  - Descriptionstring
    素材组描述。
  - AIGC
    LivenessFace
  - ProjectNamestring, 必填
    Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
    pattern: ^cv1-[0-9a-z]{5}$
  - CreateTimestring<date-time>, 必填
    创建时间。
  - UpdateTimestring<date-time>, 必填
    更新时间。
- - Idstring, 必填
    素材组 ID。
    Namestring, 必填
    素材组名称。
    Descriptionstring
    素材组描述。
    AIGC
    LivenessFace
    ProjectNamestring, 必填
    Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
    pattern: ^cv1-[0-9a-z]{5}$
    CreateTimestring<date-time>, 必填
    创建时间。
    UpdateTimestring<date-time>, 必填
    更新时间。
  - TotalCountinteger<int64>, 必填
    当前 API Key 在指定项目下符合条件的素材组总数。
    minimum: 0
  - PageNumberinteger<int64>, 必填
    页码，从 1 开始。
    minimum: 1
  - PageSizeinteger<int64>, 必填
    每页数量，最大为 100。
    minimum: 1; maximum: 100
- - Idstring, 必填
    素材 ID。
  - Namestring
    素材名称。
  - URLstring<uri>
    素材访问地址，有效期通常为 12 小时，请及时保存或使用。
  - Image
    Video
    Audio
  - GroupIdstring
    素材所属的素材组 ID。
  - Processing
    Active
    Failed
  - Strategy"Default"
    内容审核策略，当前固定为 Default。
    const: Default
  - Codestring
    处理失败码，例如人脸不一致、下载失败、格式不支持、转码失败或内容审核未通过。
    Messagestring
    处理失败详情。
  - CreateTimestring<date-time>, 必填
    创建时间。
  - UpdateTimestring<date-time>, 必填
    更新时间。
  - LastInferenceTimestring<date-time>
    素材最近一次用于提交视频生成任务的时间。任务提交后可能延迟 1–2 分钟更新；没有近期调用记录时可能不返回。
  - ProjectNamestring, 必填
    Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
    pattern: ^cv1-[0-9a-z]{5}$
- - Idstring, 必填
    素材 ID。
    Namestring
    素材名称。
    URLstring<uri>
    素材访问地址，有效期通常为 12 小时，请及时保存或使用。
    Image
    Video
    Audio
    GroupIdstring
    素材所属的素材组 ID。
    Processing
    Active
    Failed
    Strategy"Default"
    内容审核策略，当前固定为 Default。
    const: Default
    Codestring
    处理失败码，例如人脸不一致、下载失败、格式不支持、转码失败或内容审核未通过。
    Messagestring
    处理失败详情。
    CreateTimestring<date-time>, 必填
    创建时间。
    UpdateTimestring<date-time>, 必填
    更新时间。
    LastInferenceTimestring<date-time>
    素材最近一次用于提交视频生成任务的时间。任务提交后可能延迟 1–2 分钟更新；没有近期调用记录时可能不返回。
    ProjectNamestring, 必填
    Modelink 火山素材项目标识。必须先调用 GET /v1/asset-projects 获取；不支持 default，字段值区分大小写。
    pattern: ^cv1-[0-9a-z]{5}$
  - TotalCountinteger<int64>, 必填
    当前 API Key 在指定项目下符合条件的素材总数。
    minimum: 0
  - PageNumberinteger<int64>, 必填
    页码，从 1 开始。
    minimum: 1
  - PageSizeinteger<int64>, 必填
    每页数量，最大为 100。
    minimum: 1; maximum: 100
- - BytedTokenstring, 必填
    本次认证的唯一凭证，用于查询认证结果。有效期为 30 分钟，且仅支持完成一次认证。
  - H5Linkstring<uri>, 必填
    端上真人认证页面。链接使用后失效；再次认证需重新创建会话。可在链接后追加 lng=zh、lng=en 或 lng=zh-Hant 指定页面语言。
  - CallbackURLstring<uri>, 必填
    创建会话时提供的回调地址。认证结束后会附加 bytedToken、resultCode 等查询参数。
- - GroupIdstring
    真人认证成功后创建的真人人像素材组 ID。认证结果尚未就绪时可能暂不返回。
- anyOf[7]object
  删除成功，无业务字段。

object

请求体、Action、Version 或 ProjectName 不合法。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

V4 Authorization 格式非法，或 API Key 无效。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

签名错误、请求过期，或 API Key 无权调用素材接口。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

素材、素材组或真人认证会话不存在，或不属于当前 API Key。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

资源状态在更新或删除过程中发生冲突。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

请求体超过 2 MiB。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

供应商限流或配额限制。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

客户端取消请求。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

本地查询、所有权校验或状态同步失败。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

调用素材供应商失败，或供应商响应不符合契约。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

素材兼容服务、素材项目或供应商客户端暂不可用。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

object

供应商请求超时。

响应体属性

- RequestIdstring, 必填
  必填。
- Actionstring, 必填
  请求中的 Action；Action 非法时仍原样返回。
- Versionstring, 必填
  请求中的 Version；Version 非法时仍原样返回。
- Service"ark", 必填
  必填。
  const: ark
- Region"cn-beijing", 必填
  必填。
  const: cn-beijing
- - Codestring, 必填
    稳定错误码，例如 InvalidParameter、InvalidAction、InvalidAccessKey、SignatureDoesNotMatch、NotFound 或 InternalError.
  - Messagestring, 必填
    错误说明。

响应

{
  "ResponseMetadata": {
    "RequestId": "64f9aa12-71f2-4ec4-ae15-07c87bc1c561",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "Asset-20260814120500-example",
    "Name": "品牌形象正面照",
    "URL": "https://example.com/signed-asset-url",
    "AssetType": "Image",
    "GroupId": "group-20260814120000-example",
    "Status": "Active",
    "Moderation": {
      "Strategy": "Default"
    },
    "CreateTime": "2026-08-14T12:05:00+08:00",
    "UpdateTime": "2026-08-14T12:06:00+08:00",
    "ProjectName": "cv1-bogic"
  }
}