> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Seedance 素材上传 API
> 上传 Seedance 工作流所需的自定义图片、视频和音频素材
## 概览
当您的 Seedance 工作流需要使用审核通过后的素材 ID，而不是直接使用公开 URL 时，请调用此接口。
典型场景：
* 真人照片
* 写实 AI 角色或虚拟形象
* 任何需要先进入素材审核流程的内容
只有 `Status` 为 `Active` 的素材，才能用于 Seedance 生成请求。
## 何时需要上传
| 素材类型 | 常见内容 | 使用方式 |
| ------ | -------------------- | ----------------------- |
| 普通图片 | 风景、商品、建筑、动物、卡通、纯场景素材 | 直接在视频生成请求中使用公开 URL |
| 人脸图片 | 含真人的人像照片 | 先上传，等待审核，再使用审核通过后的素材 ID |
| 写实人形图片 | AI 角色、虚拟偶像、数字人、写实头像 | 先上传，等待审核，再使用审核通过后的素材 ID |
## 流程
1. 准备一个可公开访问的资源 URL。
2. 调用 [Seedance 素材上传 API](/zh/models/seedance/asset-upload)，传入 `name`、`asset_type` 和 `asset_url`。
3. 如果上传真人素材，请先完成 [Seedance 真人素材验证 API](/zh/models/seedance/visual-validate)，再将返回的 `GroupId` 作为
`group_id` 传入。
4. 上传成功后，接口会返回 `asset_id`。
5. 素材需要审核，请等待审核通过后再用于生成。调用 [Seedance 素材信息 API](/zh/models/seedance/asset-info)，持续轮询直到
`Status` 变为 `Active`。
6. 在 Seedance 视频生成请求中使用审核通过后的素材标识，通常格式为 `asset://xxx`。
## 请求示例
```json theme={null}
{
"name": "fashion-model-front",
"asset_type": "Image",
"asset_url": "https://example.com/assets/fashion-model-front.jpg",
"group_id": "group-20260331145705-*****"
}
```
非真人素材可省略 `group_id`。真人素材必须传入认证结果接口返回的 `GroupId`。
## 响应示例
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"AssetId": "asset-20260420153000-ab12c"
}
}
```
## 在 Seedance 中使用已上传素材
审核通过后，可将素材 ID 传入以下 Seedance 视频生成接口字段：
* `img_urls`
* `last_frame_image`
* `reference_images`
* `reference_videos`
* `reference_audios`
## 相关资源
查询上传状态，并等待素材变为可用
获取真人素材上传所需的 Asset Group ID
在图生视频请求中使用已上传图片素材
在参考生视频请求中使用已上传图片、视频和音频素材
## OpenAPI
````yaml zh/models/seedance/asset-upload.json post /api/v1/client/job/asset-upload
openapi: 3.0.0
info:
title: Seedance 素材上传 API
description: 用于上传 Seedance 工作流所需自定义图片、视频和音频素材的 API 文档
version: 1.0.0
contact:
name: Technical Support
email: support@crun.ai
servers:
- url: https://api.crun.ai
description: API 服务器
security:
- ApiKeyAuth: []
paths:
/api/v1/client/job/asset-upload:
post:
summary: 上传 Seedance 自定义素材
description: 上传 Seedance 工作流所需的自定义图片、视频和音频素材。
operationId: seedance/asset-upload
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- asset_type
- asset_url
properties:
name:
type: string
description: 素材显示名称。
minLength: 1
maxLength: 64
example: fashion-model-front
asset_type:
type: string
description: 上传素材的类型。
enum:
- Image
- Video
- Audio
example: Image
asset_url:
type: string
format: uri
description: |-
可公开访问的素材 URL。图片、视频和音频素材仅支持通过 URL 传入，不支持 Base64。
## 输入要求
### 通用规则
- 传入图片、视频或音频素材时，**仅支持 URL**
- **不支持 Base64 编码**
---
## 图片要求
- **格式**：jpeg、png、webp、bmp、tiff、gif、heic、heif
- **宽高比（宽 / 高）**：`(0.4, 2.5)`
- **尺寸（像素）**：`(300, 6000)`
- **文件大小**：单张图片小于 30 MB
---
## 视频要求
- **格式**：mp4、mov
- **分辨率**：480p、720p
- **时长**：`[2, 15]` 秒
- **尺寸要求**：
- 宽高比（宽 / 高）：`[0.4, 2.5]`
- 宽高（像素）：`[300, 6000]`
- 总像素：宽 × 高属于 `[409600, 927408]`
- **文件大小**：单个视频不超过 50 MB
- **帧率（FPS）**：`[24, 60]`
---
## 音频要求
- **格式**：wav、mp3
- **时长**：`[2, 15]` 秒
- **文件大小**：单个音频不超过 15 MB
example: https://example.com/assets/fashion-model-front.jpg
group_id:
type: string
nullable: true
description: >-
真人素材上传时可选的 Asset Group ID。请通过 [Seedance 真人素材验证
API](/zh/models/seedance/visual-validate)
获取该值，仅在上传需要绑定到对应真人的素材时传入。
example: group-20260331145705-*****
example:
name: fashion-model-front
asset_type: Image
asset_url: https://example.com/assets/fashion-model-front.jpg
group_id: group-20260331145705-*****
responses:
'200':
description: 已接受上传请求
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
data:
type: object
properties:
AssetId:
type: string
description: >-
返回的素材标识。请通过 [Seedance 素材信息
API](/models/seedance/asset-info) 查询其状态，并仅在
`Status` 变为 `Active` 后使用。
example: asset-20260420153000-ab12c
example:
code: 200
message: success
data:
AssetId: asset-20260420153000-ab12c
'422':
description: 参数校验错误
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ApiResponse'
- type: object
properties:
errors:
type: array
description: 详细的参数校验错误信息
items:
type: string
example:
- Value error, asset upload failed
example:
code: 422
message: Asset upload failed. Please try other resources.
'500':
$ref: '#/components/responses/Error'
components:
schemas:
ApiResponse:
type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 422
- 429
- 455
- 500
- 501
- 505
description: |-
响应状态码
- **200**：成功，请求已成功处理
- **401**：未授权，缺少认证信息或认证无效
- **402**：额度不足，账户额度不足以完成本次操作
- **404**：资源不存在，请求的资源或接口不存在
- **422**：参数校验错误，请求参数未通过校验
- **429**：请求过于频繁，已超出当前资源的调用限制
- **455**：服务不可用，系统当前正在维护中
- **500**：服务器错误，处理请求时发生了意外错误
- **501**：生成失败，内容生成任务执行失败
- **505**：功能已禁用，请求的功能当前不可用
message:
type: string
description: 响应消息；失败时为错误说明
example: success
responses:
Error:
description: 服务器错误
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: |-
所有接口均需通过 API Key 进行认证。
获取 API Key：
1. 访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取你的 API Key
使用方式：
在请求头中添加：
x-api-key: YOUR_API_KEY
注意事项：
- 请妥善保管你的 API Key，不要泄露给他人
- 如果怀疑 API Key 已泄露，请立即在管理页面中重置
````