curl --fail-with-body --silent --show-error \
--request POST \
--url 'https://code.heihuzi.ai/?Action=CreateAssetGroup&Version=2024-01-01' \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"Name": "我的角色", "GroupType": "AIGC", "Description": "古风短剧人物"}'
Seedance 视频
Seedance 视频:素材管理
按火山方舟素材接口的格式创建、查询、修改、删除素材组和素材,生成视频时用 asset:// 引用自己的人物形象。
POST
/
?Action=CreateAsset&Version=2024-01-01
curl --fail-with-body --silent --show-error \
--request POST \
--url 'https://code.heihuzi.ai/?Action=CreateAssetGroup&Version=2024-01-01' \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"Name": "我的角色", "GroupType": "AIGC", "Description": "古风短剧人物"}'
素材管理接口和火山方舟「素材」接口的格式相同:请求地址是
运行前设置环境变量
返回
返回
返回
返回
失败时
https://code.heihuzi.ai/?Action=<接口名>&Version=2024-01-01,方法都是 POST,正文是 JSON。把图片存成素材、等审核通过后,就能在创建视频时用 asset://<素材 ID> 作参考图,让同一个人物形象出现在多个视频里。
请使用绑定「Seedance 视频」分组的 API Key。创建、查询、修改、删除素材都不收费,生成视频按视频计费。
curl --fail-with-body --silent --show-error \
--request POST \
--url 'https://code.heihuzi.ai/?Action=CreateAssetGroup&Version=2024-01-01' \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"Name": "我的角色", "GroupType": "AIGC", "Description": "古风短剧人物"}'
HEIHUZI_API_KEY。上面的示例创建一个素材组。
使用流程
CreateAssetGroup创建素材组,记下返回的Id(形如group-…)。CreateAsset把图片链接存进素材组,记下返回的Id(形如asset-…)。- 每隔几秒调用
GetAsset,直到Status变成Active(审核通过)。 - 创建视频时,在参考图里填
asset://<素材 ID>。 - 不再需要时,用
DeleteAsset、DeleteAssetGroup删除。
身份验证
两种方式任选一种:- API Key:请求头
Authorization: Bearer <你的 API Key>,和其他接口一样。 - 火山签名:沿用火山方舟官方 SDK 的签名方式,把 AccessKey 和 SecretKey 都填成你的便利店 API Key,服务地址换成
https://code.heihuzi.ai,Region 填cn-beijing,Service 填ark。签名时间和服务器时间相差不能超过 15 分钟;同一个签名的写操作(创建、修改、删除)只能用一次,重发要重新签名。
素材组
CreateAssetGroup 创建素材组
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Name | string | 否 | 名称,最多 64 个字,建议填写,方便按名称筛选 |
GroupType | string | 否 | 只能填 AIGC,不填时默认 AIGC |
Description | string | 否 | 说明,最多 300 个字 |
{"Id": "group-…"}。
每个账号最多 10 个素材组,已有 10 个时再创建返回 409 AssetLimitExceeded,请先删除不用的素材组。
GetAssetGroup 查询素材组
正文{"Id": "group-…"}。返回素材组的 Id、Name、Description、ProjectName 等信息,ProjectName 固定显示 default。
ListAssetGroups 列出素材组
| 字段 | 类型 | 说明 |
|---|---|---|
Filter.Name | string | 按名称筛选 |
MaxResults | integer | 每页条数 |
NextToken | string | 上一页返回的 NextToken,取下一页时填 |
Items(素材组列表)和 NextToken(还有下一页时才有)。只列出你自己创建的素材组。
UpdateAssetGroup 修改素材组
正文填Id,以及要改的 Name、Description。
DeleteAssetGroup 删除素材组
正文{"Id": "group-…"}。
素材
CreateAsset 创建素材
curl --fail-with-body --silent --show-error \
--request POST \
--url 'https://code.heihuzi.ai/?Action=CreateAsset&Version=2024-01-01' \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"GroupId": "group-20261101210510-qjdgs", "URL": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg", "AssetType": "Image", "Name": "红苹果"}'
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
GroupId | string | 是 | 你自己创建的素材组 ID |
URL | string | 是 | 公网可访问的图片链接(http 或 https),图片要求见创建视频的「图片」一节 |
AssetType | string | 是 | 只能填 Image,填其他值返回 400 InvalidParameter |
Name | string | 否 | 名称,最多 64 个字 |
{"Id": "asset-…"}。
- 每个账号大约每 20 秒只能创建 1 个素材,太快会返回 429
TooManyRequests,响应头Retry-After写着要等几秒,等够后重试即可。查询、列表、修改、删除不受这个间隔限制。 - 素材入库前会经过内容审核。不是图片的文件会被直接拒绝(400
InvalidParameter.FormatUnsupported)。 - 本站没有开放真人身份认证,建议使用 AI 生成的虚拟人物形象;不保证真人照片能通过审核。
- 可以在请求头里带
Idempotency-Key(最长 128 个字符):网络中断后用同一个键重发,会拿到同一个素材,不会重复创建。
GetAsset 查询素材
正文{"Id": "asset-…"}。返回素材的 Id、Name、GroupId、AssetType、Status、URL、ProjectName 等信息。
Status为Active表示审核通过,可以用来生成视频;为Failed表示未通过;其他状态表示还在处理,请稍后再查。URL是素材的临时下载链接,会过期,不要长期保存。
ListAssets 列出素材
curl --fail-with-body --silent --show-error \
--request POST \
--url 'https://code.heihuzi.ai/?Action=ListAssets&Version=2024-01-01' \
--header "Authorization: Bearer $HEIHUZI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"Filter": {"GroupIds": ["group-20261101210510-qjdgs"], "Statuses": ["Active"]}, "MaxResults": 10}'
| 字段 | 类型 | 说明 |
|---|---|---|
Filter.GroupIds | string[] | 按素材组筛选 |
Filter.Statuses | string[] | 按状态筛选,如 ["Active"] |
MaxResults | integer | 每页条数 |
NextToken | string | 上一页返回的 NextToken,取下一页时填;筛选条件要和上一页相同 |
Items(素材列表)和 NextToken(还有下一页时才有)。只列出你自己的素材。
UpdateAsset 修改素材
正文填Id 和新的 Name。
DeleteAsset 删除素材
正文{"Id": "asset-…"}。正在生成中的视频引用了这个素材时不能删除,返回 409 ResourceInUse,等视频结束后再删。
用素材生成视频
素材状态为Active 后,在创建视频的参考图里填素材 ID,一个视频里可以同时引用多个素材:
{
"model": "doubao-seedance-2-0-mini-260615",
"content": [
{"type": "text", "text": "图片1的女剑客在月下的竹林里舞剑,镜头缓慢环绕"},
{"type": "image_url", "image_url": {"url": "asset://asset-20261101165309-6tc9s"}, "role": "reference_image"}
],
"resolution": "480p",
"ratio": "16:9",
"duration": 5,
"generate_audio": false
}
素材有效期
素材和素材组不会永久保存,到期后自动删除:- 用过的素材:最后一次用它生成视频后保留 7 天;期间每用一次,都从那次重新算 7 天。
- 没用过的素材:创建后保留 24 小时。
- 素材组:最后一次往组里添加素材后保留 24 小时。组里还有素材时不会删除;组里的素材都删除后,到期的素材组随即自动删除。
GetAsset、GetAssetGroup 查询会返回 404 ResourceNotFound。需要长期使用的人物形象,请保存好原图,过期后重新创建素材。
响应格式
成功:{
"ResponseMetadata": {"RequestId": "…", "Action": "CreateAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing"},
"Result": {"Id": "asset-20261101210526-mgqhj"}
}
ResponseMetadata 里多一个 Error:
{
"ResponseMetadata": {"RequestId": "…", "Action": "GetAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing",
"Error": {"Code": "ResourceNotFound", "Message": "asset or asset group not found"}}
}
与火山官方接口的差别
- 只有一个项目,
ProjectName不填或填default,填其他值返回 400InvalidParameter。 - 每个账号只能看到、修改、使用自己创建的素材组和素材,别人的素材 ID 一律当作不存在。
- 正文只接受上面列出的字段,带了其他字段返回 400
InvalidParameter。 - 不支持真人认证相关接口,调用返回 400
InvalidActionOrVersion。
错误响应
| HTTP | Error.Code | 说明 |
|---|---|---|
| 400 | InvalidParameter | 字段不符合要求,例如带了不支持的字段、ProjectName 不是 default、AssetType 不是 Image |
| 400 | InvalidParameter.FormatUnsupported | URL 指向的文件不是支持的图片格式 |
| 400 | InvalidActionOrVersion | 接口名不在上面列出的范围内,或 Version 不是 2024-01-01 |
| 401 | — | API Key 不正确 |
| 401 | SignatureDoesNotMatch | 火山签名校验失败,例如签名后正文被改动 |
| 401 | SignatureReplayed | 同一个签名的写操作重复提交,请重新签名 |
| 401 | RequestExpired | 签名时间和服务器时间相差超过 15 分钟 |
| 404 | ResourceNotFound | 素材或素材组不存在,或不属于你 |
| 409 | ResourceInUse | 素材正被未结束的视频使用,暂时不能删除 |
| 409 | AssetLimitExceeded | 素材组已达 10 个上限,请先删除不用的素材组 |
| 429 | TooManyRequests | 创建素材太快,按响应头 Retry-After 等待后重试 |