Skip to main content
POST
素材管理接口和火山方舟「素材」接口的格式相同:请求地址是 https://code.heihuzi.ai/?Action=<接口名>&Version=2024-01-01,方法都是 POST,正文是 JSON。把图片存成素材、等审核通过后,就能在创建视频时用 asset://<素材 ID> 作参考图,让同一个人物形象出现在多个视频里。 请使用绑定「Seedance 视频」分组的 API Key。创建、查询、修改、删除素材都不收费,生成视频按视频计费。
运行前设置环境变量 HEIHUZI_API_KEY。上面的示例创建一个素材组。

使用流程

  1. CreateAssetGroup 创建素材组,记下返回的 Id(形如 group-…)。
  2. CreateAsset 把图片链接存进素材组,记下返回的 Id(形如 asset-…)。
  3. 每隔几秒调用 GetAsset,直到 Status 变成 Active(审核通过)。
  4. 创建视频时,在参考图里填 asset://<素材 ID>。
  5. 不再需要时,用 DeleteAsset、DeleteAssetGroup 删除。

身份验证

两种方式任选一种:
  • API Key:请求头 Authorization: Bearer <你的 API Key>,和其他接口一样。
  • 火山签名:沿用火山方舟官方 SDK 的签名方式,把 AccessKey 和 SecretKey 都填成你的便利店 API Key,服务地址换成 https://code.heihuzi.ai,Region 填 cn-beijing,Service 填 ark。签名时间和服务器时间相差不能超过 15 分钟;同一个签名的写操作(创建、修改、删除)只能用一次,重发要重新签名。
不需要登录便利店网页,也不需要额外的确认步骤。

素材组

CreateAssetGroup 创建素材组

返回 {"Id": "group-…"}。 每个账号最多 10 个素材组,已有 10 个时再创建返回 409 AssetLimitExceeded,请先删除不用的素材组。

GetAssetGroup 查询素材组

正文 {"Id": "group-…"}。返回素材组的 Id、Name、Description、ProjectName 等信息,ProjectName 固定显示 default。

ListAssetGroups 列出素材组

返回 Items(素材组列表)和 NextToken(还有下一页时才有)。只列出你自己创建的素材组。

UpdateAssetGroup 修改素材组

正文填 Id,以及要改的 Name、Description。

DeleteAssetGroup 删除素材组

正文 {"Id": "group-…"}。

素材

CreateAsset 创建素材

返回 {"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 列出素材

返回 Items(素材列表)和 NextToken(还有下一页时才有)。只列出你自己的素材。

UpdateAsset 修改素材

正文填 Id 和新的 Name。

DeleteAsset 删除素材

正文 {"Id": "asset-…"}。正在生成中的视频引用了这个素材时不能删除,返回 409 ResourceInUse,等视频结束后再删。

用素材生成视频

素材状态为 Active 后,在创建视频的参考图里填素材 ID,一个视频里可以同时引用多个素材:

素材有效期

素材和素材组不会永久保存,到期后自动删除:
  • 用过的素材:最后一次用它生成视频后保留 7 天;期间每用一次,都从那次重新算 7 天。
  • 没用过的素材:创建后保留 24 小时。
  • 素材组:最后一次往组里添加素材后保留 24 小时。组里还有素材时不会删除;组里的素材都删除后,到期的素材组随即自动删除。
到期删除的素材和素材组不能恢复,再用 GetAsset、GetAssetGroup 查询会返回 404 ResourceNotFound。需要长期使用的人物形象,请保存好原图,过期后重新创建素材。

响应格式

成功:
失败时 ResponseMetadata 里多一个 Error:

与火山官方接口的差别

  • 只有一个项目,ProjectName 不填或填 default,填其他值返回 400 InvalidParameter。
  • 每个账号只能看到、修改、使用自己创建的素材组和素材,别人的素材 ID 一律当作不存在。
  • 正文只接受上面列出的字段,带了其他字段返回 400 InvalidParameter。
  • 不支持真人认证相关接口,调用返回 400 InvalidActionOrVersion。

错误响应