素材库概述

入口

素材接口使用 POST，通过 Action 和 Version 选择操作：

部署入口	素材地址
统一入口 `/ai`	`https://ai.tuiwo.vip/ai?Action=<Action>&Version=2024-01-01`

素材接口统一使用 /ai 入口。

鉴权

Authorization: Bearer <TUIWO_API_TOKEN>
Content-Type: application/json

使用 TUIWO API Key，不是AccessKey/SecretKey。
Key 必须绑定具体分组，并至少允许当前分组的一款的 Seedance 模型。
平台会把请求代理到当前分组中具备素材能力的渠道，客户不直接接触服务凭证。
不是参考协议 AK/SK 签名流程；如果需要原生 AK/SK，请直接使用Seedance。

通用请求

{
  "Action": "ListAssets",
  "Version": "2024-01-01"
}

实际格式是 URL 查询参数，不是请求体字段：

curl -X POST 'https://ai.tuiwo.vip/ai?Action=ListAssets&Version=2024-01-01' \
  -H 'Authorization: Bearer $TUIWO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"PageNumber":1,"PageSize":20}'

请求体上限为 10 MiB。Version 固定为 2024-01-01。

通用响应

成功时，业务数据在 Result；平台元数据在 ResponseMetadata：

{
  "ResponseMetadata": {
    "RequestId": "0217...",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "ASSET_ID"
  }
}

错误可能出现在 ResponseMetadata.Error，即使 HTTP 状态为 200，也必须检查：

{
  "ResponseMetadata": {
    "Error": {
      "Code": "ContentRestricted",
      "Message": "content moderation failed"
    }
  }
}

平台自身的鉴权、分组和代理错误使用：

{
  "error": {
    "code": "AccessDenied",
    "message": "The pinned channel is not available"
  }
}

Action 一览

分类	Action	说明
素材组	`CreateAssetGroup`	创建素材组
素材组	`GetAssetGroup`	查询素材组
素材组	`ListAssetGroups`	分页查询素材组
素材组	`UpdateAssetGroup`	修改名称或描述
素材组	`DeleteAssetGroup`	删除素材组及其下全部素材
素材	`CreateAsset`	创建图片、视频或音频素材
素材	`GetAsset`	查询素材状态与信息
素材	`ListAssets`	分页/筛选素材
素材	`UpdateAsset`	修改素材名称
素材	`DeleteAsset`	删除素材
真人认证	`CreateVisualValidateSession`	创建活体认证会话
真人认证	`GetVisualValidateResult`	查询认证结果

CreateRealValidateH5 在当前代理 allowlist 中，但服务端公开文档未开放该 Action；在确认前不要依赖它。

详细页面

最小工作流

CreateAssetGroup 创建素材组，读取 Result.Id。
CreateAsset 把图片/视频/音频上传到该组，读取 Result.Id。
轮询 GetAsset 或 ListAssets，等到 Status = Active。
视频请求中用 asset://<素材ID> 引用。

{
  "type": "image_url",
  "image_url": {"url": "asset://ASSET_ID"},
  "role": "reference_image"
}

限制

只有 Active 素材可以用于生成；Processing 需要继续轮询，Failed 需查看 Error。
素材组和素材属于当前授权工作空间；同一分组内的客户可以看到彼此创建的素材组，包括真人认证组。只与可信客户共享分组。
当前分组必须恰好有一个具备素材能力的服务配置；多个配置返回 409 AmbiguousServiceConfiguration，没有配置返回 404 NotFound。
平台不存储视频文件；可直连的素材 URL 原样返回，其他服务端 URL 返回平台签名代理地址。代理 URL 按素材类型使用 /v1/media/image、/v1/media/audio、/v1/media/video，下载名自动使用素材 ID 加扩展名。
部分模型服务会返回 Pending 状态；Statuses 过滤由服务端解释，不能保证只返回 Active，客户端必须逐项检查。
分页大小以实际返回为准；平台当前默认上限约 50，协议上限为 100。
删除素材或素材组不可恢复。

常见错误

code	说明
`InvalidActionOrVersion`	Action 不在允许列表，或 Version 不是 `2024-01-01`
`QuotaExceeded`	素材容量额度用尽
`FlowLimitExceeded`	并发或频率超限
`ContentRestricted`	内容审核未通过
`DownloadFailed`	服务端无法下载素材 URL
`TypeMismatch`	素材类型与内容不符
`FormatUnsupported` / `FormatUndetectable`	格式不支持或无法识别
`FaceMismatch`	真人素材与认证本人不一致
`VisualValidateFailed` / `VisualValidateSessionExpired`	真人认证失败或会话过期
`InternalError`	服务端内部错误

目录