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

# Seedance 2.0 查询素材

> 使用 `GET /api/asset/get` 查询 Seedance 2.0 素材详情和处理状态。

# Seedance 2.0 查询素材

这个接口用于查询通过 `POST /api/asset/createMedia` 创建的素材。

* 根据素材 ID 查询素材详情
* 返回素材 URL、类型和状态
* 可用于确认素材是否已从 `Processing` 变为 `Active`
* 查询接口使用裸素材 ID；视频生成接口使用 `asset://{asset_id}` 引用素材

## 方法与路径

```http theme={null}
GET /api/asset/get?id={asset_id}
```

<RequestExample>
  ```bash 查询素材 cURL theme={null}
  curl -X GET "https://magic666.top/api/asset/get?id=asset-20260528143012-a8x7k" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

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

  resp = requests.get(
      "https://magic666.top/api/asset/get",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"id": "asset-20260528143012-a8x7k"},
      timeout=30,
  )

  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const assetId = "asset-20260528143012-a8x7k";

  const response = await fetch(
    `https://magic666.top/api/asset/get?id=${encodeURIComponent(assetId)}`,
    {
      method: "GET",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
      },
    }
  );

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

## 从素材 ID 到视频生成引用

`GET /api/asset/get` 的 `id` 参数只接收素材 ID 本身，例如 `asset-20260528143012-a8x7k`。不要在查询接口里加 `asset://` 前缀。

当 `Result.Status` 为 `Active` 后，可以把同一个素材 ID 拼成 `asset://{asset_id}`，传给视频生成接口中的素材字段。

| 目的    | 字段                                                      | 示例                                                               |
| ----- | ------------------------------------------------------- | ---------------------------------------------------------------- |
| 首帧生视频 | `first_image`                                           | `"first_image": "asset://asset-20260528143012-a8x7k"`            |
| 尾帧约束  | `last_image`                                            | `"last_image": "asset://asset-20260528143351-b2n6q"`             |
| 参考图片  | `reference_image_urls`                                  | `"reference_image_urls": ["asset://asset-20260528143012-a8x7k"]` |
| 参考视频  | `reference_video_url` 或 `reference_video_urls`          | `"reference_video_urls": ["asset://asset-20260528143708-k9m2p"]` |
| 参考音频  | `reference_audios`、`reference_audio_urls` 或 `audio_url` | `"reference_audio_urls": ["asset://asset-20260528144123-r4s6n"]` |

```json theme={null}
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "参考素材中的产品外观和镜头运动，生成一条广告感短视频",
  "duration": 6,
  "aspect_ratio": "16:9",
  "reference_image_urls": ["asset://asset-20260528143012-a8x7k"],
  "reference_video_urls": ["asset://asset-20260528143708-k9m2p"]
}
```

## 响应示例

<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 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": "Active"
    }
  }
  ```

  ```json 400 - 缺少素材 ID theme={null}
  {
    "error": {
      "message": "id is required",
      "type": "invalid_request_error"
    }
  }
  ```

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

  ```json 404 - 素材不存在 theme={null}
  {
    "error": {
      "message": "asset not found",
      "type": "invalid_request_error"
    }
  }
  ```

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

  ```json 500 - 服务端处理失败 theme={null}
  {
    "error": {
      "message": "Failed to query asset",
      "type": "server_error"
    }
  }
  ```
</ResponseExample>

## 认证

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

## Query Parameters

<ParamField query="id" type="string" required>
  素材 ID，例如 `asset-20260528143012-a8x7k`。这里使用裸 ID，不要传 `asset://asset-20260528143012-a8x7k`。
</ParamField>

## Response

<ResponseField name="ResponseMetadata" type="object">
  请求元信息。
</ResponseField>

<ResponseField name="Result.Id" type="string">
  素材 ID。用于查询时保持裸 ID；用于视频生成素材字段时拼成 `asset://{Result.Id}`。
</ResponseField>

<ResponseField name="Result.Name" type="string">
  素材名称。
</ResponseField>

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

<ResponseField name="Result.AssetType" type="string">
  素材类型。常见值为 `image`、`video`、`audio`。
</ResponseField>

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

## 使用场景

### 创建素材后确认状态

创建素材接口返回 `Processing` 后，使用素材 ID 查询，直到 `Result.Status` 变为 `Active`。

```http theme={null}
GET /api/asset/get?id=asset-20260528143012-a8x7k
```

### 检查素材类型

读取 `Result.AssetType`，确认素材是否按预期注册为 `image`、`video` 或 `audio`。

```json theme={null}
{
  "Result": {
    "AssetType": "video",
    "Status": "Active"
  }
}
```

## 注意事项

* `id` 必须来自素材创建接口返回的 `Result.Id`。
* `GET /api/asset/get` 的 `id` 参数不要带 `asset://` 前缀。
* `Processing` 表示素材仍在处理，建议等待 `Active` 后再用于视频生成。
* `Failed` 表示素材处理失败，需要重新检查原始 URL、文件格式或上游限制。

## 相关页面

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