跳转到主要内容
Seedance 2.0 涉及两套鉴权、两个端点：
  • 素材库管理（建组 / 上传 / 查询 / 删除）：火山引擎原生接口，用 AK/SK 签名，直连 open.volcengineapi.com。APIYI 不中转这部分。
  • 视频生成（含引用 asset://）：经 APIYI 网关 + Bearer sk-...（令牌须勾选 SeeDance2 分组）。
关键结论（已实测）：用 APIYI 提供的 AK/SK 把素材入库后，私域 asset:// 可直接用 APIYI 的 sk- 令牌生成视频——因为 APIYI 的 SeeDance2 通道底层就是同一个火山账号。模型选型、定价、分辨率表见 Seedance 2.0 概览，视频生成接口见 视频生成 API。

​
为什么需要素材库

Seedance 2.0 内置防 Deepfake / 侵权拦截，不接受直接上传含真人人脸的参考图。要让生成视频中的人物面部、服装稳定一致，需先把虚拟人像素材入库成「可信资产」，得到 asset:// ID 后在视频生成里引用。
  • Asset Group（素材组）：管理同一虚拟人物的多张素材。
  • Asset（素材）：单个图片 / 视频 / 音频文件，入库并预处理为 Active 后方可用于生成。

​
一、准备工作

  1. AK/SK：火山控制台「访问控制（IAM）」获取，AK 形如 AKLT...。
  2. 素材库权限：给 AK/SK 所属 IAM 用户加自定义策略，否则报 403 AccessDenied： 
    {"Statement":[{"Effect":"Allow","Action":["ark:*Asset*"],"Resource":["*"]}]}
  3. 首次签授权函：首次建组需在控制台「我的 → 虚拟人像」签署授权函（一次性）。
  4. ProjectName：素材所属项目需与视频生成令牌一致（多数素材库接口必须显式传 ProjectName，否则默认查 default 项目）。

​
二、火山 AK/SK 签名（Python）

SK 直接当 UTF-8 字符串作为签名派生密钥，不要 base64 解码（实测 base64 会返回 SignatureDoesNotMatch）。
import hashlib, hmac, json
from datetime import datetime, timezone
from urllib.parse import quote
import requests

AK, SK = "你的AK", "你的SK"
HOST, SERVICE, REGION, VERSION = "open.volcengineapi.com", "ark", "cn-beijing", "2024-01-01"

def _h(s): return hashlib.sha256(s.encode()).hexdigest()
def _hmac(k, s): return hmac.new(k, s.encode(), hashlib.sha256).digest()

def call(action, body):
    body_str = json.dumps(body)
    x_date = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    short, bh = x_date[:8], _h(body_str)
    q = "&".join(f"{quote(k,safe='-_.~')}={quote(v,safe='-_.~')}"
                 for k, v in sorted({"Action": action, "Version": VERSION}.items()))
    signed = "content-type;host;x-content-sha256;x-date"
    canon = "\n".join(["POST", "/", q,
        f"content-type:application/json\nhost:{HOST}\nx-content-sha256:{bh}\nx-date:{x_date}",
        "", signed, bh])
    scope = f"{short}/{REGION}/{SERVICE}/request"
    sts = "\n".join(["HMAC-SHA256", x_date, scope, _h(canon)])
    ks = _hmac(_hmac(_hmac(_hmac(SK.encode(), short), REGION), SERVICE), "request")
    sig = hmac.new(ks, sts.encode(), hashlib.sha256).hexdigest()
    headers = {"Host": HOST, "Content-Type": "application/json", "X-Date": x_date,
        "X-Content-Sha256": bh,
        "Authorization": f"HMAC-SHA256 Credential={AK}/{scope}, SignedHeaders={signed}, Signature={sig}"}
    r = requests.post(f"https://{HOST}/?{q}", headers=headers, data=body_str, timeout=60)
    return r.status_code, r.json()
也可用官方 SDK 自动签名：pip install volcengine-python-sdk。上面给的是自包含 requests 版，便于直接移植到你的后端。

​
三、虚拟人像入库流程

import time
PROJECT = "你的ProjectName"

# 1. 建组
_, g = call("CreateAssetGroup", {"Name": "my_figure", "GroupType": "AIGC", "ProjectName": PROJECT})
gid = g["Result"]["Id"]

# 2. 上传素材（异步，无 SLA）
_, a = call("CreateAsset", {"GroupId": gid, "URL": "https://你的图片URL.jpg",
                            "AssetType": "Image", "ProjectName": PROJECT})
aid = a["Result"]["Id"]

# 3. 轮询到 Active
while True:
    _, info = call("GetAsset", {"Id": aid, "ProjectName": PROJECT})
    st = info.get("Result", info).get("Status")
    if st == "Active": break
    if st == "Failed": raise RuntimeError("入库失败")
    time.sleep(10)

print("可用素材:", f"asset://{aid}")
图像格式要求：jpeg / png / webp / bmp / tiff / gif / heic；宽高比（宽/高）0.4–2.5；边长 300–6000px；单张小于 30 MB。 人像最佳实践：把同一人物的全身正面图 + 人脸正面无表情特写放进同一素材组，能显著提升生成时的人物一致性。素材预处理通常很快（实测单张图约 13 秒转 Active）。

​
四、用 asset:// 生成视频（经 APIYI）

把 asset://<AssetId> 放进视频生成请求的 content 数组，role 设为 reference_image。提示词里用「图片1」指代该素材，不要直接写 Asset ID。 
import requests
url = "https://api.apiyi.com/seedance/api/v3/contents/generations/tasks"
headers = {"Authorization": "Bearer sk-你的SeeDance2令牌",
           "Content-Type": "application/json", "Accept-Encoding": "identity"}
body = {
    "model": "doubao-seedance-2-0-260128",
    "content": [
        {"type": "text", "text": "图片1中的人物正面微笑，镜头缓慢推近，自然光"},
        {"type": "image_url", "image_url": {"url": f"asset://{aid}"}, "role": "reference_image"},
    ],
    "ratio": "16:9", "duration": 5, "resolution": "720p",
}
task = requests.post(url, headers=headers, json=body).json()
# 轮询 GET {url}/{task['id']} 直到 status=succeeded，取 content.video_url
素材必须建在 APIYI SeeDance2 通道对应的火山账号下（即用 APIYI 给的 AK/SK 入库）。若引用了不属于该账号的 asset://，会返回 400 The specified asset ... is not found。

​
五、检索与管理

动作Action关键参数
查组列表ListAssetGroupsFilter.GroupType=AIGC、ProjectName、PageNumber/PageSize
查素材列表ListAssetsFilter.GroupIds、Filter.Statuses、ProjectName
查单个GetAssetId、ProjectName
删素材 / 删组DeleteAsset / DeleteAssetGroupId、ProjectName
统一传 ProjectName：ListAssets / ListAssetGroups 不传会默认查 default 项目、返回 0 条；DeleteAssetGroup 不传会返回 404。
限流（账号维度）：GetAsset 100 QPS；CreateAsset 按高级创作权益包；其余多为 10 QPS。

​
六、真人人脸（真人人像）

真人人脸不是素材库 API 的某个参数，而是火山体验中心里独立的真人认证流程，无法纯 API 完成：
1

创建真人资产组

体验中心「我的 → 真人人像 → 管理素材 → 创建资产组」。
2

确认授权

确认授权主体与目的，同意人脸信息处理规则。
3

真人认证

被拍摄者本人完成人脸核身认证——每个资产组一次，之后同一演员加妆发造型无需重复认证。
4

自动绑定

完成后，对应账号自动获得该肖像使用权（谁授权谁使用），生成专属素材组。
合规：火山要求真人视频生成需「实际人物经过验证或事先获得法律授权」，真人认证从源头锁定肖像权归属。
产品落地建议：虚拟人像走本页 API 自动化上传；真人人脸引导用户到火山控制台完成认证后，把素材 ID 回填到你的系统再调用生成。真人素材的 ID 引用格式、是否与虚拟人像共享权益包、是否需额外肖像授权书等细节，建议先与 API易 团队 / 火山官方确认。

​
七、常见错误

现象原因处理
401 SignatureDoesNotMatch签名错误（误把 SK base64 解码 / 时间偏差 / canonical 拼错）SK 直接 UTF-8；核对 canonical request
403 AccessDenied: ark:*IAM 用户无素材库权限加策略 ark:*Asset* 并绑定到用户
建组失败首次未签授权函控制台手动建组触发签署
列表返回 0 条 / 删组 404未传 ProjectName所有素材库请求统一带 ProjectName
生成 400 asset not found素材不在该网关对应火山账号下 / ID 写错用 APIYI 给的 AK/SK 入库；核对 Asset ID
火山官方参考文档（复制到浏览器打开）：私域素材库指南 volcengine.com/docs/82379/2333565、素材库 API 参考 volcengine.com/docs/82379/2333601、录入真人形象素材 volcengine.com/docs/82379/2315856。