素材库 Python SDK​

Ark Assets SDK 用于管理 Seedance 素材库，封装真人认证、素材组、素材上传、状态轮询以及同步/异步调用。SDK 为单文件设计，可以直接放入现有 Python 项目。

与视频 API 的鉴权不同

素材库接口使用 AK/SK HMAC 签名；视频生成和任务查询使用 API Key。不要把 API Key 填入 VOLC_AK 或 VOLC_SK。

下载​

下载包会在文档构建时自动匹配当前站点的 API 域名。SDK 要求 Python 3.9 或更高版本，并依赖：

bash
pip install "volcengine-python-sdk>=5.0.40"

将 ark_assets.py 放入项目目录即可使用。

配置​

请从 控制台 获取或管理 AK/SK。密钥只应保存在服务端环境变量或密钥管理系统中，不能提交到代码仓库，也不能放入浏览器、桌面客户端或移动端安装包。

bash
export VOLC_AK="YOUR_AK"
export VOLC_SK="YOUR_SK"
export VOLC_REGION="cn-beijing"
export VOLC_HOST="art-api.yuyuflow.com"
export VOLC_SCHEME="https"
export VOLC_VERIFY_SSL="true"
export VOLC_PROJECT="default"

也可以在代码中显式配置：

python
from ark_assets import ArkAssetsConfig, ArkAssetsClient

client = ArkAssetsClient(ArkAssetsConfig(
    ak="YOUR_AK",
    sk="YOUR_SK",
    region="cn-beijing",
    host="art-api.yuyuflow.com",
    scheme="https",
    verify_ssl=True,
    project_name="default",
))
配置项环境变量默认值说明
akVOLC_AK空Access Key，必填
skVOLC_SK空Secret Key，必填
regionVOLC_REGIONcn-beijing签名区域
hostVOLC_HOSTart-api.yuyuflow.com当前站点对应的素材 API 域名
schemeVOLC_SCHEMEhttps请求协议
verify_sslVOLC_VERIFY_SSLtrue是否校验 TLS 证书
project_nameVOLC_PROJECTdefault资源所属项目，大小写敏感

30 秒快速开始​

下面完成“创建 AIGC 素材组 → 上传图片 → 等待素材可用”的完整流程：

python
from ark_assets import ArkAssetsClient

client = ArkAssetsClient()

group = client.create_asset_group(
    name="my-portrait",
    group_type="AIGC",
    description="production assets",
)
group_id = group["Id"]

asset = client.upload_and_wait(
    group_id=group_id,
    url="https://example.com/portrait.jpg",
    asset_type="Image",
    name="portrait-front",
    interval=5,
    timeout=300,
)

print(asset["Id"], asset["Status"])

上传请求成功不代表素材已经可以用于视频生成。只有 Status=Active 的素材才应写入视频请求：

text
asset://mas_xxxxxxxxx

SDK 方法与 REST API​

真人认证​

SDK 方法用途或接口
create_liveness_session(callback_url)创建真人认证会话
get_liveness_result(byted_token)查询真人认证结果
run_liveness_flow(...)创建会话并自动轮询，直到取得 GroupId

完整业务流程请阅读私域真人人像使用指南。

素材组管理​

SDK 方法REST API
create_asset_group(...)创建素材组
list_asset_groups(...)查询素材组列表
get_asset_group(group_id)查询素材组
update_asset_group(...)更新素材组
delete_asset_group(group_id)删除素材组

素材管理​

SDK 方法REST API
create_asset(...)创建素材
list_assets(...)查询素材列表
get_asset(asset_id)查询素材
update_asset(asset_id, name)更新素材
delete_asset(asset_id)删除素材
wait_asset_active(...)轮询至 Active、Failed 或超时
upload_and_wait(...)创建素材并等待可用

真人认证示例​

python
from ark_assets import ArkAssetsClient

client = ArkAssetsClient()

def show_session(byted_token: str, h5_link: str) -> None:
    print("请让终端用户打开以下链接完成真人认证：")
    print(h5_link)

result = client.run_liveness_flow(
    callback_url="https://your-app.example.com/portrait/callback",
    poll_interval=15,
    timeout=1800,
    on_session=show_session,
)

print("真人素材组：", result["GroupId"])

真人认证会打开 H5 页面。认证完成后，SDK 返回真人对应的素材组 ID；上传到该组的素材还会进行人脸一致性校验。

异步调用​

AsyncArkAssetsClient 与同步客户端的方法名称一致，可用于并发查询或上传：

python
import asyncio
from ark_assets import AsyncArkAssetsClient

async def main():
    client = AsyncArkAssetsClient()
    first, second = await asyncio.gather(
        client.create_asset_group(name="group-1"),
        client.create_asset_group(name="group-2"),
    )
    print(first["Id"], second["Id"])

asyncio.run(main())

异步客户端通过线程代理同步请求。调用量较大时仍应限制并发，并对限流响应采用退避重试。

错误处理​

python
from ark_assets import ArkAssetsClient, ArkAssetsError

client = ArkAssetsClient()

try:
    client.create_asset(
        group_id="mag_xxxxxxxxx",
        url="https://example.com/image.jpg",
        asset_type="Image",
    )
except ArkAssetsError as error:
    print(error.action)
    print(error.status)
    print(error.body)
错误含义与建议
DownloadFailed素材服务下载或处理远程 URL 失败。确认 URL 无需 Cookie、无防盗链且长期公网可访问。
FaceMismatch上传素材与真人认证基准人脸不一致。
QuotaWriteQPMExceeded创建素材写请求超过速率配额，降低并发并退避重试。
QuotaSharedPoolExceeded共享素材池容量已满，持续高频重试通常无效，请等待容量释放或联系管理员。
asset_pool_mismatch素材与目标模型不在同一隔离素材池，应改用同池模型或重新创建素材。

生产环境建议​

  • 保持 verify_ssl=True。
  • AK/SK 只保存在服务端，并定期轮换。
  • 上传 URL 应稳定、无需登录、无需 Cookie，并在素材处理完成前保持可访问。
  • 轮询必须设置超时；遇到限流时使用退避策略，不要无间隔重试。
  • 删除素材或素材组前，确认没有视频任务仍在引用对应的 asset:// ID。

下一步​