素材项

状态

状态	说明
`Pending`	部分模型服务（如）返回的排队状态；不是可用状态
`Processing`	服务端正在下载、转码和审核
`Active`	可用；可在视频请求中用 `asset://<ID>` 引用
`Failed`	处理失败；查看 `Error.Code` 和 `Error.Message`

创建后不要立即用于生成，先轮询到 Active。

CreateAsset

curl -X POST 'https://ai.tuiwo.vip/ai?Action=CreateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer $TUIWO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "GroupId": "GROUP_ID",
    "AssetType": "Image",
    "URL": "https://example.com/product.png",
    "Name": "商品主图"
  }'

字段	类型	必填	说明
`GroupId`	string	是	素材组 ID
`AssetType`	string	是	`Image`、`Video` 或 `Audio`
`URL`	string	是	可公开访问的素材 URL
`Name`	string	是	素材名称
`ProjectName`	string	否	默认 `default`

响应 Result.Id。URL 必须能被服务端下载；平台不会把文件转存到自身存储，也不会自动把 Base64 转成 URL。

GetAsset

curl -X POST 'https://ai.tuiwo.vip/ai?Action=GetAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer $TUIWO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"Id":"ASSET_ID"}'

字段	类型	必填	说明
`Id`	string	是	素材 ID
`ProjectName`	string	否	默认 `default`

响应 Result：

字段	类型	说明
`Id`	string	素材 ID
`Name`	string	名称
`URL`	string	原生素材地址或平台签名代理地址（其他服务端）；代理下载名使用素材 ID
`AssetType`	string	`Image`、`Video` 或 `Audio`
`Status`	string	`Pending`、`Processing`、`Active` 或 `Failed`；只有 `Active` 可用
`GroupId`	string	所属素材组
`ProjectName`	string	项目名
`CreateTime`	string	创建时间
`UpdateTime`	string	更新时间
`LastInferenceTime`	string	最后使用时间（如有）
`Error`	object	失败时的 `Code`、`Message`
`Moderation`	object	审核信息（如有）

ListAssets

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 '{"Filter":{"GroupIds":["GROUP_ID"],"Statuses":["Active"]},"PageNumber":1,"PageSize":20}'

字段	类型	说明
`Filter.GroupType`	string	按组类型筛选
`Filter.GroupIds`	string[]	按组 ID 筛选
`Filter.Name`	string	按名称筛选
`Filter.Statuses`	string[]	`Pending`、`Processing`、`Active`、`Failed`；过滤由服务端解释，仍需逐项检查 `Status`
`NextToken`	string	游标分页标记
`MaxResults`	integer	1–100
`SortBy`	string	`CreateTime`、`UpdateTime` 等
`SortOrder`	string	`Desc` 或 `Asc`
`PageNumber`	integer	页码
`PageSize`	integer	每页数量；平台当前默认上限约 50

响应 Result 包含 Items、NextToken、PageNumber、PageSize、TotalCount；Items 的字段与 GetAsset.Result 一致。请遍历分页，不要假设第一页包含全部素材。

UpdateAsset

curl -X POST 'https://ai.tuiwo.vip/ai?Action=UpdateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer $TUIWO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"Id":"ASSET_ID","Name":"新名称"}'

字段	类型	必填	说明
`Id`	string	是	素材 ID
`Name`	string	否	新名称
`ProjectName`	string	否	默认 `default`

DeleteAsset

curl -X POST 'https://ai.tuiwo.vip/ai?Action=DeleteAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer $TUIWO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"Id":"ASSET_ID"}'

删除不可恢复；删除后不能再用于生成。

常见失败原因

错误	说明
`DownloadFailed`	服务端无法下载 URL
`ContentRestricted`	审核未通过
`TypeMismatch`	`AssetType` 与实际内容不符
`FormatUnsupported` / `FormatUndetectable`	格式不支持或无法识别
`FaceMismatch`	真人素材与认证本人不一致
`DurationTooShort` / `DurationTooLong`	音频或视频时长不符合要求
`FileSizeTooLarge`	文件过大
`InternalError`	服务端内部错误

在视频请求中引用

素材进入 Active 后：

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

视频和音频分别使用 video_url / audio_url 搭配对应 role。asset:// 素材必须属于当前工作空间。

目录