> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.geeknow.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 2.0 创建素材

> 使用 `POST /api/asset/createMedia` 创建图片、视频或音频素材，供 Seedance 2.0 视频任务引用。

# Seedance 2.0 创建素材

这个接口把一个公网素材 URL 注册到素材库，并返回后续视频生成可引用的素材 ID。

* 使用异步处理模式，创建后返回素材 ID 和 `Processing` 状态
* 通过 `assetType` 区分图片、视频和音频素材
* 创建成功后可用 `GET /api/asset/get` 查询素材是否变为 `Active`
* 生成视频时可把 `Result.Id` 拼成 `asset://{asset_id}`，用于首帧、尾帧、参考图、参考视频或参考音频字段

## 方法与路径

```http theme={null}
POST /api/asset/createMedia
```

<RequestExample>
  ```bash 图片素材 cURL theme={null}
  curl -X POST https://td.geeknow.top/api/asset/createMedia \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/assets/product-reference.png",
      "name": "product-reference.png",
      "assetType": "image"
    }'
  ```

  ```bash 视频素材 cURL theme={null}
  curl -X POST https://td.geeknow.top/api/asset/createMedia \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/assets/camera-motion.mp4",
      "name": "camera-motion.mp4",
      "assetType": "video"
    }'
  ```

  ```bash 音频素材 cURL theme={null}
  curl -X POST https://td.geeknow.top/api/asset/createMedia \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/assets/background-music.mp3",
      "name": "background-music.mp3",
      "assetType": "audio"
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://td.geeknow.top/api/asset/createMedia",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "url": "https://example.com/assets/product-reference.png",
          "name": "product-reference.png",
          "assetType": "image",
      },
      timeout=60,
  )

  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://td.geeknow.top/api/asset/createMedia", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://example.com/assets/product-reference.png",
      name: "product-reference.png",
      assetType: "image",
    }),
  });

  console.log(await response.json());
  ```
</RequestExample>

## assetType 枚举怎么理解

`assetType` 用来告诉接口：这个 `url` 应该按哪种素材处理。你只需要传一个 `url`，不需要自己传 `imageUrls`、`videoUrls` 或 `audioUrls`。

| `assetType` | 含义   | 等价素材列表             | 常见用途        |
| ----------- | ---- | ------------------ | ----------- |
| `image`     | 图片素材 | `imageUrls: [url]` | 首帧图、尾帧图、参考图 |
| `video`     | 视频素材 | `videoUrls: [url]` | 参考视频、镜头运动参考 |
| `audio`     | 音频素材 | `audioUrls: [url]` | 背景音乐、参考音频   |

例如你传入：

```json theme={null}
{
  "url": "https://example.com/assets/camera-motion.mp4",
  "assetType": "video"
}
```

它表达的含义是：`https://example.com/assets/camera-motion.mp4` 是一个视频素材，等价于把这个地址放进视频素材列表：

```json theme={null}
{
  "videoUrls": ["https://example.com/assets/camera-motion.mp4"]
}
```

同理，如果 `assetType` 是 `image`，同一个 `url` 会按图片素材处理；如果是 `audio`，同一个 `url` 会按音频素材处理。

## 素材 ID 与引用 URI

素材创建成功后，响应里的 `Result.Id` 是素材 ID，例如 `asset-20260528143012-a8x7k`。这个值有两种用法：

| 场景         | 写法               | 示例                                                    |
| ---------- | ---------------- | ----------------------------------------------------- |
| 查询素材状态     | 直接使用素材 ID        | `GET /api/asset/get?id=asset-20260528143012-a8x7k`    |
| 在视频生成里引用素材 | 加上 `asset://` 前缀 | `"first_image": "asset://asset-20260528143012-a8x7k"` |

`asset://asset-20260528143012-a8x7k` 表示“引用素材库中这个 ID 对应的素材”。它不是公网 URL，不能直接在浏览器中打开；如果需要查看素材原始地址或当前状态，使用 [查询素材](./asset-get)。

常见写法：

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "让首帧图中的人物自然转身，看向镜头",
  "duration": 6,
  "aspect_ratio": "9:16",
  "first_image": "asset://asset-20260528143012-a8x7k"
}
```

多参考素材也使用同样的 URI 写法：

```json theme={null}
{
  "reference_image_urls": ["asset://asset-20260528143012-a8x7k"],
  "reference_video_urls": ["asset://asset-20260528143708-k9m2p"],
  "reference_audio_urls": ["asset://asset-20260528144123-r4s6n"]
}
```

## 响应示例

<ResponseExample>
  ```json 200 - 素材创建任务已提交 theme={null}
  {
    "ResponseMetadata": {
      "Action": "seedance2"
    },
    "Result": {
      "Id": "asset-20260528143012-a8x7k",
      "Name": "product-reference.png",
      "URL": "https://example.com/assets/product-reference.png",
      "AssetType": "image",
      "Status": "Processing"
    }
  }
  ```

  ```json 400 - 请求体不是合法 JSON theme={null}
  {
    "error": {
      "message": "invalid character '}' looking for beginning of object key string",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 - 未提供有效 API Key theme={null}
  {
    "error": {
      "message": "无效的令牌",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 402 - 额度不足 theme={null}
  {
    "error": {
      "message": "余额不足",
      "type": "insufficient_quota"
    }
  }
  ```

  ```json 429 - 请求过于频繁 theme={null}
  {
    "error": {
      "message": "rate limit exceeded",
      "type": "rate_limit_exceeded"
    }
  }
  ```

  ```json 500 - 服务端处理失败 theme={null}
  {
    "error": {
      "message": "url is required",
      "type": "do_request_failed"
    }
  }
  ```
</ResponseExample>

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="url" type="string" required>
  素材公网 URL。必须是服务端可访问的地址，例如 `https://example.com/assets/product-reference.png`。
</ParamField>

<ParamField body="name" type="string">
  素材名称。建议传入带扩展名的文件名，例如 `product-reference.png`、`camera-motion.mp4` 或 `background-music.mp3`。
</ParamField>

<ParamField body="assetType" type="string">
  素材类型。支持 `image`、`video`、`audio`；未传时按 `image` 处理。建议始终显式传入，避免视频或音频 URL 被当作图片素材。
</ParamField>

## Response

<ResponseField name="ResponseMetadata" type="object">
  请求元信息。Seedance 2.0 素材接口通常会返回 `Action`。
</ResponseField>

<ResponseField name="Result.Id" type="string">
  素材 ID，例如 `asset-20260528143012-a8x7k`。查询素材时直接传这个 ID；在视频生成请求中引用素材时写成 `asset://asset-20260528143012-a8x7k`。
</ResponseField>

<ResponseField name="Result.Name" type="string">
  素材名称。通常来自请求里的 `name`。
</ResponseField>

<ResponseField name="Result.URL" type="string">
  原始素材 URL。
</ResponseField>

<ResponseField name="Result.AssetType" type="string">
  素材类型，通常与请求里的 `assetType` 一致。
</ResponseField>

<ResponseField name="Result.Status" type="string">
  素材状态。常见值为 `Processing`、`Active`、`Failed`。
</ResponseField>

## 使用场景

### 创建参考图片素材

把商品图、角色图、场景图等注册为 `image` 素材，后续在视频生成请求中作为首帧、尾帧或参考图使用。

```json theme={null}
{
  "url": "https://example.com/assets/character.png",
  "name": "character.png",
  "assetType": "image"
}
```

### 创建参考视频素材

把一段镜头运动、构图或动作参考注册为 `video` 素材，后续作为参考视频使用。

```json theme={null}
{
  "url": "https://example.com/assets/motion-reference.mp4",
  "name": "motion-reference.mp4",
  "assetType": "video"
}
```

### 创建参考音频素材

把背景音乐、口播或氛围音注册为 `audio` 素材，后续作为参考音频使用。

```json theme={null}
{
  "url": "https://example.com/assets/theme.mp3",
  "name": "theme.mp3",
  "assetType": "audio"
}
```

## 注意事项

* `/api/asset/createMedia` 只接收一个 `url`；不要把 `imageUrls`、`videoUrls`、`audioUrls` 直接作为请求字段传入。
* `assetType` 是大小写敏感的公开参数，推荐使用小写的 `image`、`video`、`audio`。
* 创建成功只代表素材任务已提交。使用前建议调用 [查询素材](./asset-get) 确认 `Result.Status` 已变为 `Active`。
* 查询素材时使用裸素材 ID，例如 `asset-20260528143012-a8x7k`；视频生成字段中引用素材时使用 `asset://asset-20260528143012-a8x7k`。
* 如果素材 URL 无法访问、下载超时或格式不被上游接受，素材状态可能变为 `Failed`。

## 相关页面

* [Seedance 2.0 概览](./overview)
* [创建视频任务](./generation)
* [查询素材](./asset-get)