使用 Seedance 私域素材库

PinduCloud 私域素材库用于保存可重复使用的图片、视频和音频，并将素材归入 Seedance 素材组。素材审核完成后，生成任务通过 asset://<AssetId> 引用素材。

素材库分为 AIGC 素材和已认证真人两类。普通建组接口创建 AIGC 组；真人组必须通过真人认证与人像素材流程获得，组类型为 LivenessFace。认证成功后仍需上传对应人像、等待审核，再用于生成任务。

注意： 素材列表中的 id、group_id 和 asset_id 用途不同：

id 是平台素材记录的数字 ID，只用于素材刷新、删除等管理接口。
group_id 是素材组 ID，用于素材列表筛选和上传请求。
asset_id 是素材标识，审核状态为 Active 后，将它写成 asset://<AssetId> 放入生成任务的媒体 URL 字段。

preview_url（如果返回）用于预览。有效且模型服务可访问时，也可以作为普通公网媒体 URL 输入；但临时签名地址会过期，不适合替代稳定的 asset://<AssetId> 引用。

鉴权和响应

程序调用使用与视频生成相同的 API Key，接口前缀为 /v1/seedance：

Authorization: Bearer <PINDUCLOUD_API_KEY>

下面示例适用于 Bash，使用环境变量保存地址和 API Key：

export BASE_URL="https://video.pinducloud.com.cn"
export API_KEY="sk-your-api-key"

控制台和本文接口共享当前用户的素材数据。程序使用本文列出的 API Key 接口，无需获取浏览器登录凭证，也无需重复上传控制台已有素材。

用户级共享与权限

同一 PinduCloud 用户的有效 API Key 共享该用户的全部素材组和媒体，包括通过控制台或其他 Key 创建的数据；无需按 Key 重建素材组或重复上传。
不同用户相互隔离。请求中的 user_id 不能改变资源归属。
同用户的 Key 可以查询、上传、刷新、改名和删除素材；轮换 PinduCloud API Key 不会改变已有素材的归属。
查询素材不按 Key 的模型列表拆分；创建素材组时检查所选模型和分组的访问权限，生成任务仍单独检查调用 Key 的模型权限及模型是否可用。
Key 被禁用、删除、过期、额度耗尽，或不符合 IP、用户状态、分组访问限制时，请求会按现有 API Key 认证规则被拒绝；用户的素材不会因此删除。
素材管理本身不扣视频生成额度，生成任务另行计费。所有 Key 共用用户级素材限流，当前为每分钟 60 次，文件上传另受上传限流约束。

成功响应通常包含：

{
  "success": true,
  "message": "",
  "data": {}
}

除明确返回 HTTP 202 的异步处理接口和外部地址校验错误外，管理接口通常使用 HTTP 200 返回业务结果，因此无论 HTTP 状态码如何，都需要检查 success。错误响应通常为：

{
  "success": false,
  "message": "错误说明"
}

素材状态和生命周期

素材创建或上传成功后不会立即可用于生成。素材记录通常经历以下状态：

状态	含义	是否可以用于生成
`Processing`、`Pending`	素材仍在处理或审核	否
`Active`、`Success`、`Succeeded`	素材接口报告处理完成	可尝试生成，仍以模型受理结果为准
`Failed`	素材处理或审核失败	否
`Deleting`	素材或素材组正在删除	否

服务会在后台同步处理中素材的状态。列表页面在存在待处理素材时会定时重新获取列表；也可以调用单个素材的刷新接口立即检查一次。客户端不应把上传接口返回 202 误认为素材已经可以生成。处理完成也不代表生成账号已完成素材同步或具备全部使用权限，生成接口仍可能返回素材同步错误。

控制台上传本地文件

登录 PinduCloud，打开 私域素材库（/seedance-assets）。
在 AIGC 素材中创建并选中普通素材组；真人素材请先在 已认证真人中完成认证。
将文件拖入素材列表区域，或点击上传按钮选择一个或多个文件。
上传队列会逐个处理文件，并分别显示排队、上传中、已完成和失败状态。
单个文件上传完成后，素材记录通常仍为 Processing。等待素材状态变为 Active（接口原始值也可能是 Success 或 Succeeded）后，再使用列表中的 asset_id 组成 asset://<AssetId>。

文件上传接口按 MIME 类型识别素材；MIME 缺失时会按扩展名补充判断。控制台支持图片、视频和音频文件，常见扩展名包括：

图片：avif、bmp、gif、heic、heif、jpeg、jpg、png、webp
视频：avi、m4v、mkv、mov、mp4、webm
音频：aac、flac、m4a、mp3、oga、ogg、wav

上传大小上限如下：

类型	最大大小
图片	30 MB
视频	50 MB
音频	15 MB

文件不能是空文件。文件名最多 64 个字符；未填写名称时使用本地文件名。上传接口只执行类型、大小和文件基础条件校验，生成任务仍需满足创建 Seedance 视频生成任务中的媒体格式、尺寸、时长和帧率要求。

API 接口

接口列表

方法	路径	用途
GET	`/v1/seedance/asset-groups`	列出当前用户的素材组
GET	`/v1/seedance/asset-groups/:id`	查询单个素材组详情
POST	`/v1/seedance/asset-groups`	创建普通 AIGC 素材组
PUT	`/v1/seedance/asset-groups/:id`	修改素材组名称、说明和标签
DELETE	`/v1/seedance/asset-groups/:id`	删除素材组及其素材
POST	`/v1/seedance/validation-sessions`	创建真人认证会话
GET	`/v1/seedance/validation-sessions/:id`	查询认证进度和成功后的素材组
GET	`/v1/seedance/assets`	分页列出素材
GET	`/v1/seedance/assets/:id`	查询单个素材详情
POST	`/v1/seedance/assets/upload`	上传本地文件
POST	`/v1/seedance/assets`	登记外部媒体地址
POST	`/v1/seedance/assets/:id/refresh`	立即刷新单个素材状态
DELETE	`/v1/seedance/assets/:id`	删除单个素材
POST	`/v1/seedance/assets/batch-delete`	批量删除素材

素材组修改、删除以及素材刷新、删除路径中的 :id 都是响应中的数字 id；素材列表筛选和上传字段中的 group_id 使用素材组响应里的字符串 group_id。

列出素材组

curl --request GET "$BASE_URL/v1/seedance/asset-groups" \
  --header "Authorization: Bearer $API_KEY"

响应中的 group_id 用于后续列出素材和上传文件：

支持 search（名称或组 ID 模糊搜索）、group_id / group_ids、ids（平台数字 ID）、 status / statuses（active、deleting、all）、created_after、created_before、 sort_by 和 sort_order。时间、排序和批量参数的规则与下面的素材列表一致。

响应中的 group_type 区分 AIGC 与 LivenessFace。当前列表接口没有按 group_type 筛选的参数，调用方可读取该字段分类显示；分页查询时需遍历所需页，不能只过滤第一页就认为拿到了全部真人素材组。

不传分页参数时保留全部组的 data 数组；显式传入 p 或 page_size 后启用分页，响应保留 data 并增加 total、page、page_size。例如：

curl --get "$BASE_URL/v1/seedance/asset-groups" \
  --header "Authorization: Bearer $API_KEY" \
  --data-urlencode "search=product" \
  --data-urlencode "p=1" \
  --data-urlencode "page_size=24" \
  --data-urlencode "sort_by=created_at" \
  --data-urlencode "sort_order=desc"

{
  "success": true,
  "message": "",
  "data": [
    {
      "id": 12,
      "group_id": "asset-group-xxxxxxxx",
      "name": "product-assets",
      "group_type": "AIGC",
      "status": "Active"
    }
  ]
}

创建普通素材组

素材组名称必填，去除首尾空白后不能为空，最多 64 个字符；同一用户不能创建同名素材组，名称比较不区分大小写。

通过 API Key 创建时还必须提供 model（最多 191 个字符），例如 doubao-seedance-2-0-fast-260128。模型必须在该 Key 允许访问的范围内；模型未开放或暂时无可用服务时，创建失败。可用模型通过 GET /v1/models 查询。

model 用于选择建组所需的模型服务，不是素材的独占模型标签。其他模型能否引用仍取决于模型能力和素材权限。修改组名称不会改变素材类型。

该接口固定创建 AIGC 组，不接受 GroupType，包括 GroupType: "AIGC"。创建真人组请使用认证会话接口，不要传入 GroupType: "LivenessFace" 尝试代替认证。

curl --request POST "$BASE_URL/v1/seedance/asset-groups" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"product-assets","model":"doubao-seedance-2-0-fast-260128"}'

创建成功后保存返回的 id 和 group_id。后续请求使用 group_id 选择该组，修改或删除该组时使用数字 id。

修改素材组信息

name 必填，最多 64 字符；description 可选，最多 1024 字符；tags 可选，最多 512 字符，类型为字符串。可选字段省略时保留原值，传空字符串时清空。同名限制与创建一致，不能通过编辑改变 group_type 或取得真人认证资格。

curl --request PUT "$BASE_URL/v1/seedance/asset-groups/12" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"product-assets-v2","description":"商品参考素材","tags":"商品,展示"}'

成功后返回更新后的素材组对象。处于 Deleting 状态的素材组不能重命名。

删除素材组

curl --request DELETE "$BASE_URL/v1/seedance/asset-groups/12" \
  --header "Authorization: Bearer $API_KEY"

成功受理返回 HTTP 202 和 {"success":true,"message":"asset group deletion queued","data":null}。删除素材组会同时清理组内素材和存储文件，普通组和真人组使用同一接口。删除过程中组和素材会进入 Deleting 状态；系统自动重试暂时失败的清理，也可调用同一路径触发重试。确认素材组从列表消失后，才表示删除流程完成。删除前请确认没有任务仍在引用其中的素材。

上传本地文件

curl --request POST "$BASE_URL/v1/seedance/assets/upload" \
  --header "Authorization: Bearer $API_KEY" \
  --form "group_id=asset-group-xxxxxxxx" \
  --form "file=@./character.png" \
  --form "name=character.png"

表单字段：

字段	必填	说明
`group_id`	是	素材组的字符串 `group_id`
`file`	是	图片、视频或音频文件
`name`	否	素材名称，最多 64 个字符；默认使用文件名
`asset_type`	否	`Image`、`Video` 或 `Audio`；填写时必须与文件类型一致，控制台通常不需要填写

成功返回 HTTP 202，表示文件已进入素材处理流程：

{
  "success": true,
  "data": {
    "id": 101,
    "asset_id": "asset-xxxxxxxx",
    "group_id": "asset-group-xxxxxxxx",
    "name": "character.png",
    "asset_type": "Image",
    "status": "Processing",
    "preview_url": "https://media.example.com/private-assets/xxxxxxxx.png?signature"
  }
}

响应中的 asset_id 可以先保存，但只有状态变为 Active、Success 或 Succeeded 后才能通过 asset:// 在生成任务中使用。preview_url 可能为空或在有效期结束后失效，不能将它长期保存为固定输入地址。

登记外部媒体地址

此接口用于 API 调用方已有可访问媒体地址的情况；控制台上传本地文件使用上面的 /upload 接口，不需要在页面中手动输入地址。

curl --request POST "$BASE_URL/v1/seedance/assets" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "group_id": "asset-group-xxxxxxxx",
    "source_url": "https://cdn.example.com/character.png",
    "asset_type": "Image",
    "name": "character.png"
  }'

字段要求：

字段	必填	说明
`group_id`	是	素材组的字符串 `group_id`
`source_url`	是	最长 2048 个字符的 HTTP 或 HTTPS 地址；不能使用本地路径、`asset://`、凭证或片段，并须通过服务端的地址访问策略
`asset_type`	是	`Image`、`Video` 或 `Audio`
`name`	否	素材名称，最多 64 个字符

成功返回 HTTP 202，状态从 Processing 开始。此接口保留外部地址作为素材来源；预览时可能直接使用该地址。外部地址必须能被服务端访问，并且仍需满足生成任务对媒体格式和大小的要求。

列出素材

curl --get "$BASE_URL/v1/seedance/assets" \
  --header "Authorization: Bearer $API_KEY" \
  --data-urlencode "group_id=asset-group-xxxxxxxx" \
  --data-urlencode "p=1" \
  --data-urlencode "page_size=24" \
  --data-urlencode "asset_type=all" \
  --data-urlencode "status=all"

查询参数：

参数	必填	取值或默认值	说明
`group_id`	否	不填写表示当前用户的全部素材	按素材组筛选
`p`	否	默认 `1`	页码，从 1 开始
`page_size`	否	默认 `10`，最大 `100`	每页数量
`search`	否	空	不区分大小写搜索名称或 `asset_id`，最多 128 个字符
`asset_type`	否	`all`	`all`、`image`、`video`、`audio`
`status`	否	`all`	`all`、`processing`、`deleting`、`active`、`failed`
`group_ids`	否	空	多个字符串组 ID，与 `group_id` 互斥
`asset_id` / `asset_ids`	否	空	单个 / 多个 `asset_id` 精确匹配，两者互斥
`ids`	否	空	多个平台数字素材 ID
`statuses`	否	空	多个状态，与 `status` 互斥
`asset_types`	否	空	多个类型，与 `asset_type` 互斥
`created_after`	否	空	平台记录创建时间大于等于该时间，RFC3339
`created_before`	否	空	平台记录创建时间严格小于该时间，RFC3339
`sort_by`	否	`id`	`id`、`created_at`、`updated_at`、`name`
`sort_order`	否	`desc`	`asc` 或 `desc`

批量值可以用逗号分隔或重复参数，如 statuses=active,processing。每个批量参数最多 100 个元素（去重前），自动去重，但不接受空元素。同字段多值取并集，不同筛选条件取交集；all 不可与其他状态或类型混用。ID 最多 128 个字符。状态、类型和排序方向不区分大小写；搜索中的 %、_、# 按普通文字匹配。

时间示例：2026-09-20T00:00:00Z，也可使用带时区偏移的 RFC3339 时间。时间范围为左闭右开，开始时间必须早于结束时间。创建及更新时间均指平台记录时间。默认按数字 ID 倒序；其他排序字段相同时以 ID 同方向排序。页码超出末页时返回末页，空结果返回第一页；并发增删期间页码分页不保证快照一致。

非法参数、单复数冲突、非正整数分页参数返回 HTTP 400。page_size 超过 100 时截断为 100；旧的 ps、size 分页别名继续支持。

例如查询多个组中已就绪或处理中的图片、视频：

curl --get "$BASE_URL/v1/seedance/assets" \
  --header "Authorization: Bearer $API_KEY" \
  --data-urlencode "group_ids=group-a,group-b" \
  --data-urlencode "statuses=active,processing" \
  --data-urlencode "asset_types=image,video" \
  --data-urlencode "sort_by=created_at" \
  --data-urlencode "sort_order=desc" \
  --data-urlencode "page_size=24"

响应示例：

{
  "success": true,
  "data": [
    {
      "id": 101,
      "asset_id": "asset-xxxxxxxx",
      "group_id": "asset-group-xxxxxxxx",
      "name": "character.png",
      "asset_type": "Image",
      "status": "Active",
      "preview_url": "https://media.example.com/private-assets/xxxxxxxx.png?signature"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 24,
  "has_pending": false
}

has_pending 表示当前用户（或 group_id / group_ids 指定的素材组）是否仍有 Processing、 Pending 或 Deleting 素材。它不是当前页的数量，不受 ID、名称、时间、类型、状态或分页筛选影响；即使当前 status 只请求 Active，同一组范围内的待处理素材也会使它为 true。

通常每 5 秒查询一次列表即可，has_pending: false 后停止轮询。平台负责同步素材审核状态，不需要为每个素材反复调用刷新接口。网络超时不等于创建失败，上传或生成请求不要盲目重发，应先查询已创建的素材或任务，避免重复创建。

preview_url 的行为与素材来源有关：文件素材使用临时预览地址，列表会提供当前可用地址；外部地址素材可能使用登记时的地址。预览地址可能为空、过期或暂时不可用，但这不改变 asset_id 和素材审核状态，也不改变任务引用格式。重复使用素材时，优先采用 asset://<AssetId>；若直接提交公网 URL，则按普通外部媒体处理，需要保证模型服务读取时仍可访问。

上传的文件不会在审核通过后自动删除，保留至用户删除素材或素材组。临时预览链接失效不表示原文件已删除；重新查询列表可获取当前预览地址。

查询单个素材或素材组

curl "$BASE_URL/v1/seedance/assets/101" \
  --header "Authorization: Bearer $API_KEY"

curl "$BASE_URL/v1/seedance/asset-groups/12" \
  --header "Authorization: Bearer $API_KEY"

路径使用平台数字 id，成功返回 success/message/data，其中 data 为单个对象。不存在或不属于当前用户的记录统一返回 HTTP 404；非法 ID 返回 HTTP 400。这些查询返回已同步的状态，不会立即触发审核状态更新。素材详情包含临时 preview_url，预览暂时不可用时仍返回记录，地址为空或省略；需要立即检查审核进度时使用下面的刷新接口。

这些详情接口同时适用于 AIGC 与已认证真人素材。真人认证进度需要查询认证会话，素材详情中的 Active 与认证会话的 Succeeded 是两个不同阶段。

立即刷新单个素材状态

curl --request POST "$BASE_URL/v1/seedance/assets/101/refresh" \
  --header "Authorization: Bearer $API_KEY"

路径中的 101 是列表响应中的数字 id，不是 asset_id。接口会立即检查该素材的当前状态并返回完整素材记录；文件素材的 preview_url 也会重新生成。刷新不会改变素材引用格式，也不会删除素材文件。

删除单个素材

curl --request DELETE "$BASE_URL/v1/seedance/assets/101" \
  --header "Authorization: Bearer $API_KEY"

成功受理返回 HTTP 202 和 {"success":true,"data":null}，表示已加入删除队列。素材会暂时处于 Deleting，系统完成文件和素材清理后从列表移除。重复调用删除接口可触发重试；确认记录消失后再视为完成。普通素材和真人素材均适用。

批量删除素材

一次最多提交 100 个数字 id，重复 ID 会自动去重：

curl --request POST "$BASE_URL/v1/seedance/assets/batch-delete" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"ids":[101,102,103]}'

接口返回 HTTP 202，表示符合当前用户归属的素材已加入删除队列：

{
  "success": true,
  "message": "3 assets queued for deletion",
  "data": {
    "deleted_ids": [],
    "failed_ids": [],
    "pending_ids": [101, 102, 103]
  }
}

批量接口返回的是排队结果，不是最终清理结果。pending_ids 对应的素材会暂时显示为 Deleting，清理完成后从列表消失；最终状态以再次调用列出素材接口的结果为准。不属于当前用户的 ID 不会通过响应泄露其是否存在。

在 Seedance 任务中引用素材

调用列出素材接口，取得目标素材的 asset_id。
确认素材 status 为 Active、Success 或 Succeeded；控制台会将这三种可用状态统一显示为 Active。
在 asset_id 前加上 asset://，形成完整引用： asset://<AssetId>。
将完整引用放入对应媒体对象的 URL 字段。

图片作为首帧的示例：

{
  "type": "image_url",
  "role": "first_frame",
  "image_url": {
    "url": "asset://asset-xxxxxxxx"
  }
}

参考图片、视频和音频分别使用以下结构：

[
  {
    "type": "image_url",
    "role": "reference_image",
    "image_url": {"url": "asset://asset-image-xxxxxxxx"}
  },
  {
    "type": "video_url",
    "role": "reference_video",
    "video_url": {"url": "asset://asset-video-xxxxxxxx"}
  },
  {
    "type": "audio_url",
    "role": "reference_audio",
    "audio_url": {"url": "asset://asset-audio-xxxxxxxx"}
  }
]

使用素材 ID 引用时，格式为 asset://<AssetId>。不要把数字 id、不带协议前缀的 asset_id 或 group_id 填入媒体 URL。若选择公网 URL 方式，地址需要满足普通外部媒体的可访问性和格式要求；它与私域素材 ID 引用是两种方式。

选择公网 URL 方式时，媒体必须符合所选模型的类型、格式及角色要求；地址应在模型服务读取期间持续有效。首帧、首尾帧和多模态参考素材的组合限制见创建 Seedance 视频生成任务。

常见问题

同一用户换了一把 API Key，还能查看已有素材吗

可以。素材按 PinduCloud 用户归属，而非按 API Key 归属。同一用户的另一把有效 Key 调用列表接口会得到同一套素材组和媒体，包含控制台已上传的数据。

Active 后仍提示“素材尚未同步到可用账号”

Active 是素材查询接口报告的处理状态，不保证生成接口一定受理。若生成返回 HTTP 409 和“素材尚未同步到可用账号，请稍后重试”，保留素材 ID、所用模型和错误中的 request ID，联系平台确认素材同步情况；不要把该响应视为已创建视频任务。

若错误码为 private_asset_mapping_pending，按 Retry-After 指定的秒数等待后重试，当前等待值为 5 秒。客户端始终使用原来的 asset_id，无需因切换 API Key 或模型自行更改引用。普通素材可在具备可用原件和目标服务权限时自动准备；首次调用可能需要等待。

已认证真人的认证资格不保证在不同模型服务之间自动共享。切换模型时仍需满足目标模型的真人素材权限；不能通过重复上传同一张图片替代认证。持续失败时请联系平台核查，不要仅凭同步错误断言人像审核不通过。

生成任务使用 asset:// 引用，平台不会把真人素材自动降级为普通素材来绕过认证。

上传接口返回成功但状态仍是 Processing

HTTP 202 只表示文件已经进入处理流程。后台会继续同步状态；重新列出素材，或调用 /v1/seedance/assets/:id/refresh 立即检查一次。只有状态为 Active、 Success 或 Succeeded 时才能提交生成任务。

preview_url 为空或失效

文件素材的 preview_url 是短期签名地址，列表接口会按需重新生成；预览失败时可以重新列出素材或刷新单个素材。若将它作为普通 URL 输入，需要确保有效期覆盖任务排队和模型服务读取阶段；提交时可访问不保证稍后仍可访问。稳定复用素材应优先使用 asset://<AssetId>，避免依赖已保存的旧预览地址。

使用 asset:// 仍然失败

检查以下项目：

<AssetId> 是否替换成了列表响应中的真实 asset_id，不能保留尖括号。
素材状态是否为 Active。
媒体类型、role 和生成模型是否匹配。
URL 是否完整，例如 asset://asset-xxxxxxxx，不能只填写 asset-xxxxxxxx。

删除后素材仍然显示

删除接口可能先将记录置为 Deleting，再完成文件和素材记录清理。重新列出素材，确认记录消失；如果长期停留在 Deleting，再次调用对应的单个或批量删除接口触发重试。

鉴权和响应​

用户级共享与权限​

素材状态和生命周期​

控制台上传本地文件​

API 接口​

接口列表​

列出素材组​

创建普通素材组​

修改素材组信息​

删除素材组​

上传本地文件​

登记外部媒体地址​

列出素材​

查询单个素材或素材组​

立即刷新单个素材状态​

删除单个素材​

批量删除素材​

在 Seedance 任务中引用素材​

常见问题​

同一用户换了一把 API Key，还能查看已有素材吗​

Active 后仍提示“素材尚未同步到可用账号”​

上传接口返回成功但状态仍是 Processing​

preview_url 为空或失效​

使用 asset:// 仍然失败​

删除后素材仍然显示​