Seedance 2.0 素材库

素材库用于在提交 Seedance 2.0 视频任务前，准备可重复使用的图片、视频和音频。素材按 UniAll.ai 用户隔离管理；客户端只需要使用自己的 UniAll.ai API Key、本地 mat_* 素材 ID，以及接口返回的 asset:// URI。

本文档对应 2026 年 7 月 29 日更新的公开调用契约。

概览

最短接入流程如下：

使用公网 HTTP(S) URL 和 Idempotency-Key 创建素材。
使用返回的 mat_* ID 查询，直到 status 变为 available。
从 uri 字段读取 asset:// URI。
将 URI 放入 Seedance 请求对应的结构化图片、视频或音频字段。
不再使用时主动删除，或等待素材自动到期。

当前版本只接受公网可访问的 HTTP(S) URL，不支持直接上传文件。

Base URL 与接口

本文所有示例使用以下 Base URL：

https://api.uniall.ai

操作	接口	结果
创建素材	`POST /v1/materials`	启动处理并返回本地 `mat_*` ID。
查询素材	`GET /v1/materials/{material_id}`	返回当前状态；可用后返回素材 URI。
列出素材	`GET /v1/materials`	返回当前用户可见的素材。
删除素材	`DELETE /v1/materials/{material_id}`	取消或删除素材工作流。

鉴权与幂等

素材接口与视频接口使用同一个 UniAll.ai API Key：

Authorization: Bearer sk-***
Content-Type: application/json

创建素材还必须携带幂等键：

Idempotency-Key: material-order-20260729-0001

幂等键必须包含 1 到 200 个可见 ASCII 字符，不能包含空格或控制字符。

相同用户使用相同幂等键重试同一个规范化请求时，会返回同一个本地素材工作流。
相同幂等键对应不同请求时，返回 material_idempotency_conflict。
网络超时或结果不确定时，必须使用原键重试，不要生成新键。
确实要创建一份新素材时，使用新的幂等键。

输入 URL 要求

素材源 URL 必须满足：

使用 http:// 或 https://；
在素材处理期间保持公网直连；
不依赖登录、Cookie、浏览器状态、额外请求头或内网；
返回与 type 一致的图片、视频或音频；
在素材进入终态前保持可访问。

快速开始

1. 创建素材

curl -X POST "https://api.uniall.ai/v1/materials" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: material-order-20260729-0001" \
  -d '{
    "url": "https://cdn.example.com/product.png",
    "type": "image",
    "name": "商品参考图"
  }'

接口固定返回 HTTP 202 和本地素材记录：

{
  "id": "mat_xxxxxxxxxxxxx",
  "object": "material",
  "name": "商品参考图",
  "type": "image",
  "status": "processing",
  "uri": null,
  "preview_url": null,
  "created_at": "2026-07-29T10:00:00Z",
  "available_at": null,
  "expires_at": null
}

2. 等待素材可用

curl "https://api.uniall.ai/v1/materials/mat_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-***"

建议每 3 到 5 秒查询一次。只有 status 为 available 时才能使用 uri：

{
  "id": "mat_xxxxxxxxxxxxx",
  "object": "material",
  "name": "商品参考图",
  "type": "image",
  "status": "available",
  "uri": "asset://asset-xxxxxxxxxxxxx",
  "preview_url": "https://example.com/short-lived-preview.jpg",
  "created_at": "2026-07-29T10:00:00Z",
  "available_at": "2026-07-29T10:01:00Z",
  "expires_at": "2026-07-29T12:01:00Z"
}

3. 在 Seedance 中使用 URI

将接口返回的 uri 放入对应的结构化媒体字段：

curl -X POST "https://api.uniall.ai/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance2.0",
    "resolution": "720p",
    "duration": 6,
    "content": [
      {
        "type": "text",
        "text": "保持产品外观一致，使用缓慢的电影感镜头运动。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://asset-xxxxxxxxxxxxx"
        },
        "role": "reference_image"
      }
    ]
  }'

不要把 asset:// URI 写入 prompt 或其他普通文本字段。UniAll.ai 会在提交生成前校验用户归属、状态和有效期；未知、已过期、已删除或属于其他用户的素材都会被拒绝。普通 HTTP(S) 媒体输入继续按系列指南中的规则使用。

创建素材

POST /v1/materials

请求参数

参数	类型	必填	说明
`url`	string	是	公网 HTTP(S) 图片、视频或音频 URL。
`type`	string	是	`image`、`video` 或 `audio`。
`name`	string	否	用户可见的素材名称。
`real_person`	object	否	真人图片或视频使用的授权声明和回跳配置。
`real_person.consent_confirmed`	boolean	使用 `real_person` 时必填	必须为 JSON 布尔值 `true`，表示接入方已经单独取得真人同意。
`real_person.callback_url`	string	使用 `real_person` 时必填	真人认证完成后的浏览器回跳地址；生产环境必须使用 HTTPS。

真人素材

真人图片和真人视频必须明确声明已取得授权，并由真人本人完成浏览器活体认证。真人音频暂不支持。

curl -X POST "https://api.uniall.ai/v1/materials" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: real-person-material-20260729-0001" \
  -d '{
    "url": "https://cdn.example.com/person.jpg",
    "type": "image",
    "name": "已授权真人头像",
    "real_person": {
      "consent_confirmed": true,
      "callback_url": "https://client.example.com/material-complete"
    }
  }'

HTTP 202 可能返回 verification_pending 和临时 verification_url：

{
  "id": "mat_xxxxxxxxxxxxx",
  "object": "material",
  "name": "已授权真人头像",
  "type": "image",
  "status": "verification_pending",
  "uri": null,
  "preview_url": null,
  "verification_url": "https://example.com/temporary-h5-token",
  "created_at": "2026-07-29T10:00:00Z",
  "available_at": null,
  "expires_at": null,
  "verification_expires_at": "2026-07-29T10:30:00Z"
}

让真人本人在浏览器中打开 verification_url 并完成 H5 活体认证。认证成功后，UniAll.ai 会在原工作流中自动提交实际素材，不需要再次调用 POST /v1/materials。

浏览器随后会跳转到 real_person.callback_url，并且只附加以下查询参数：

material_id=mat_xxxxxxxxxxxxx&material_status=processing

回跳时的状态可能是 creating、processing、available 或认证失败状态。回跳只表示已收到认证结果，不代表素材一定已经可用；客户端仍需继续查询素材详情。即使浏览器回跳丢失，后台恢复流程也会继续推进工作流。

verification_url 只会出现在创建响应或该请求的幂等重放响应中。查询、列表和删除响应都不会返回它。

查询素材

GET /v1/materials/{material_id}

只有当前 API Key 所属用户可以查询该素材。响应不会暴露原始输入 URL、真人认证标识、内部素材 ID、内部路由信息、凭证、H5 临时令牌或回调校验状态。

素材目前在变为可用后保留两小时。到达 expires_at 后，记录会归档为 deleted；之后用户详情接口返回 404 material_not_found。

列出素材

GET /v1/materials

查询参数	必填	说明
`type`	否	`image`、`video` 或 `audio`。
`status`	否	`creating`、`verification_pending`、`processing`、`available` 或 `delete_pending`。
`limit`	否	每页 1 到 100 条，默认 `50`。
`after`	否	上一页返回的不透明游标。

curl "https://api.uniall.ai/v1/materials?type=image&status=available&limit=20" \
  -H "Authorization: Bearer sk-***"

{
  "object": "material.list",
  "data": [
    {
      "id": "mat_xxxxxxxxxxxxx",
      "object": "material",
      "name": "商品参考图",
      "type": "image",
      "status": "available",
      "uri": "asset://asset-xxxxxxxxxxxxx",
      "preview_url": "https://example.com/short-lived-preview.jpg",
      "created_at": "2026-07-29T10:00:00Z",
      "available_at": "2026-07-29T10:01:00Z",
      "expires_at": "2026-07-29T12:01:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "opaque-cursor-value"
}

请求下一页时，把 next_cursor 原样作为 after 传入。不要解析或自行构造游标。

用户素材列表会排除失败、认证失败、认证过期、已删除、历史过期，以及已经到期但等待后台归档的记录。这些记录可以继续保留在管理员视图中用于审计和排障。

删除素材

DELETE /v1/materials/{material_id}

curl -X DELETE "https://api.uniall.ai/v1/materials/mat_xxxxxxxxxxxxx" \
  -H "Authorization: Bearer sk-***"

HTTP 200 且 status=deleted：删除已经完成。
HTTP 202 且 status=delete_pending：删除请求已接受，仍在异步处理。
真人认证尚未完成时，删除会取消本地工作流。
删除操作是幂等的；已删除素材不能再用于生成。

两种成功状态都会返回与详情接口相同的完整素材对象。

素材状态

状态	说明
`creating`	UniAll.ai 正在初始化素材工作流。
`verification_pending`	等待真人完成 H5 认证。
`verification_failed`	真人认证失败，或认证会话创建结果不确定。
`verification_expired`	真人认证会话已经过期。
`processing`	实际素材已经提交，正在处理。
`available`	素材可以用于生成请求。
`failed`	素材创建或处理失败。
`delete_pending`	删除已经提交，仍在处理。
`deleted`	删除完成；该状态可能出现在删除响应中，但查询和列表不再返回。

verification_failed、verification_expired 和 failed 都是失败终态。使用原创建幂等键重放只会返回原失败工作流；要创建新素材，请使用新的 Idempotency-Key。

安全与生命周期

verification_url 包含 H5 临时令牌，应按机密信息处理。不要写入业务日志、埋点、客服消息或公开页面。
不要记录完整的真人回跳 URL、查询参数或回调校验状态。
preview_url 是短期预览地址，不能作为永久存储或稳定的公开链接。
不要依赖查询或列表接口返回原始输入 URL。
只使用同一用户拥有、当前状态为 available 的 asset:// URI。

常见错误

错误使用 OpenAI 兼容结构：

{
  "error": {
    "message": "The material is not available.",
    "type": "invalid_request_error",
    "code": "material_not_available"
  }
}

错误码	说明
`invalid_idempotency_key`	缺少有效的 `Idempotency-Key`，或格式不符合要求。
`invalid_material_request`	URL、类型、名称或查询参数不符合要求。
`invalid_material_cursor`	`after` 不是本接口返回的有效游标。
`material_channel_unavailable`	素材服务暂不可用，或当前模型暂不支持素材输入。
`material_idempotency_conflict`	相同幂等键对应了不同请求。
`material_not_found`	素材不存在、不属于当前用户，或已经到期归档。
`material_not_available`	素材尚未可用、已经过期或已经删除。
`material_not_managed`	`asset://` URI 未登记在当前用户的 UniAll.ai 素材库中。
`visual_verification_consent_required`	真人素材没有明确确认授权同意。
`invalid_visual_verification_request`	真人素材类型或回跳地址不符合要求。
`visual_verification_create_outcome_uncertain`	首次创建认证会话的结果不确定；系统不会自动创建第二个会话。
`material_create_outcome_uncertain`	素材创建结果不确定，UniAll.ai 正在后台核对。

错误消息只包含可公开信息，不会暴露上游原始错误、内部路由或凭证。

概览​

Base URL 与接口​

鉴权与幂等​

输入 URL 要求​

快速开始​

1. 创建素材​

2. 等待素材可用​

3. 在 Seedance 中使用 URI​

创建素材​

请求参数​

真人素材​

查询素材​

列出素材​

删除素材​

素材状态​

安全与生命周期​

常见错误​

相关页面​

概览