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

# 上传素材

> 使用 `POST /v1/seedance/asset/CreateAsset` 将公网素材导入 Seedance 素材库。

# 上传素材

在指定素材组中导入素材。`URL` 用于把公网 HTTPS 资源拉取进素材库（审核/转码由服务端完成）。导入成功后返回 `AssetId`，在 [创建视频](./generation) 中推荐用 `asset://{assetId}` 引用，而不是重复填写公网 URL。

## 方法与路径

```http theme={null}
POST /v1/seedance/asset/CreateAsset
```

## 请求示例

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1/seedance/asset/CreateAsset \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
      "GroupId": "group-20260415111540-w9pkb",
      "URL": "https://example.com/reference.webp",
      "AssetType": "Image",
      "Name": "child"
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://octopusx.ai/v1/seedance/asset/CreateAsset",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
          "Accept": "application/json",
      },
      json={
          "GroupId": "group-20260415111540-w9pkb",
          "URL": "https://example.com/reference.webp",
          "AssetType": "Image",
          "Name": "child",
      },
      timeout=60,
  )
  print(resp.json())
  ```
</CodeGroup>

## 响应示例

<ResponseExample>
  ```json 200 theme={null}
  {
    "state": 1,
    "data": {
      "Id": "asset-xxx",
      "task_id": "task_xxx"
    },
    "error": null
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": "InvalidParameter",
      "message": "the parameter duration specified in the request is not valid",
      "type": "new_api_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": "Unauthorized",
      "message": "Invalid API key provided",
      "type": "new_api_error"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": "Forbidden",
      "message": "access denied",
      "type": "new_api_error"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": "RateLimitExceeded",
      "message": "当前请求频率过高，请稍后再试",
      "type": "new_api_error"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": "InternalError",
      "message": "internal server error",
      "type": "new_api_error"
    }
  }
  ```
</ResponseExample>

素材处理为异步流程，请用返回的 `task_id` 调用 [查询素材](./asset-get)，待 `Status` 为 `Active` 后再用于视频生成。

## 认证

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

## Body

<ParamField body="GroupId" type="string" required>
  素材组 ID，来自 [创建素材组](./asset-create-group) 返回的 `data.Id`。
</ParamField>

<ParamField body="URL" type="string" required>
  待导入素材的公网 HTTPS 地址。
</ParamField>

<ParamField body="AssetType" type="string" required>
  素材类型：`Image`、`Video`、`Audio`。
</ParamField>

<ParamField body="Name" type="string" required>
  素材名称。
</ParamField>

## Response

<ResponseField name="state" type="integer">
  业务状态码。
</ResponseField>

<ResponseField name="data.Id" type="string">
  素材 ID，视频生成时可写为 `asset://{Id}`。
</ResponseField>

<ResponseField name="data.task_id" type="string">
  导入任务 ID，用于 [查询素材](./asset-get)。
</ResponseField>

<ResponseField name="error" type="object | null">
  错误信息。
</ResponseField>

## 相关页面

* [Seedance-2 概览](./overview)
* [创建素材组](./asset-create-group)
* [查询素材](./asset-get)
* [创建视频](./generation)