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

# 查询素材列表

> 查询当前 API Key 用户名下的素材列表，支持按状态、类型、名称过滤。默认不返回素材资源 URL；传入 `include_resource_url=1` 时，图片和视频素材会额外返回平台/CDN 素材 URL。

查询当前 API Key 用户名下的素材列表，支持按状态、类型、名称过滤，支持分页。

```
GET /v1/assets
Authorization: Bearer <API_KEY>
```

***

## 查询参数

| 参数                     | 类型             | 说明                                                     |
| ---------------------- | -------------- | ------------------------------------------------------ |
| `status`               | string         | 按状态过滤：`processing`、`active`、`failed`。                  |
| `asset_type`           | string         | 按类型过滤：`image`、`video`、`audio`。                         |
| `name`                 | string         | 按名称模糊搜索。                                               |
| `page`                 | integer        | 页码，默认 1。                                               |
| `page_size`            | integer        | 每页数量，默认 20，最大 100。                                     |
| `include_resource_url` | integer/string | 可选。传入 `1` 时，图片和视频素材会额外返回 `resource_url`。默认不返回素材资源 URL。 |

***

## 示例

```bash theme={null}
curl "https://{your-domain}/v1/assets?asset_type=image&status=active&page=1&page_size=20&include_resource_url=1" \
  -H "Authorization: Bearer $API_KEY"
```

**响应：**

```json theme={null}
{
  "items": [
    {
      "id": "asset_6f9a4c2b8d1e3a90",
      "uri": "asset://asset_6f9a4c2b8d1e3a90",
      "object": "asset",
      "asset_type": "image",
      "name": "avatar-reference",
      "status": "active",
      "resource_url": "https://cdn.wengaocloud.com/assets/ai/domain_x/user_x/image/example.png",
      "created_at": 1779782400,
      "updated_at": 1779782460
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}
```

`resource_url` 是平台保存后的素材访问地址，通常为平台 CDN 地址；它不是视频生成请求使用的 `asset://` URI。该字段仅在传入 `include_resource_url=1` 且素材类型为 `image` 或 `video` 时返回。

***

## 素材状态

| 状态           | 说明                 | 可用于视频生成 |
| ------------ | ------------------ | ------- |
| `processing` | 平台已受理，正在保存或等待素材处理。 | 否       |
| `active`     | 素材可用。              | **是**   |
| `failed`     | 素材处理失败。            | 否       |
| `disabled`   | 素材已被平台禁用。          | 否       |


## OpenAPI

````yaml GET /v1/assets
openapi: 3.1.0
info:
  title: WengaoCloud AI Gateway API
  version: 0.1.0
  description: WengaoCloud AI 聚合平台公开 API 契约草案，覆盖 OpenAI 兼容接口、Anthropic 原生接口和平台扩展接口。
servers:
  - url: https://xxx.wengaocloud.com
    description: 问高云 API 网关根域名。OpenAI SDK 的 base_url 使用 https://xxx.wengaocloud.com/v1。
  - url: https://{tenant}.wengaocloud.com
    description: 控制台展示的租户或 OEM API 网关根域名。
    variables:
      tenant:
        default: xxx
security:
  - bearerAuth: []
tags:
  - name: models
    x-group: 模型
  - name: openai-compatible
    x-group: OpenAI 兼容接口
  - name: anthropic-native
    x-group: Anthropic 原生接口
  - name: images-v3
    x-group: 图片（V3 同步）
  - name: volcengine-images
    x-group: 图片（火山直连）
  - name: images
    x-group: 图片（V1 兼容）
  - name: async-images
    x-group: 图片异步任务
  - name: aliwan-images
    x-group: 图片（百炼万相）
  - name: videos
    x-group: 视频
paths:
  /v1/assets:
    get:
      tags:
        - videos
      summary: 查询素材列表
      description: >-
        查询当前 API Key 用户名下的素材列表，支持按状态、类型、名称过滤。默认不返回素材资源 URL；传入
        `include_resource_url=1` 时，图片和视频素材会额外返回平台/CDN 素材 URL。
      operationId: listAssets
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum:
              - processing
              - active
              - failed
        - name: asset_type
          in: query
          schema:
            type: string
            enum:
              - image
              - video
              - audio
        - name: name
          in: query
          schema:
            type: string
          description: 按名称模糊搜索。
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: include_resource_url
          in: query
          schema:
            oneOf:
              - type: integer
              - type: string
          description: 传入 `1` 时，图片和视频素材会额外返回 `resource_url`；默认不返回。
      responses:
        '200':
          description: 素材列表。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    AssetListResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AssetResponse'
        total:
          type: integer
        page:
          type: integer
        page_size:
          type: integer
    AssetResponse:
      type: object
      properties:
        id:
          type: string
          description: 平台素材 ID，格式 `asset_xxx`。
          example: asset_6f9a4c2b8d1e3a90
        uri:
          type: string
          description: 素材 URI，格式 `asset://asset_xxx`，视频生成请求中使用此值。
          example: asset://asset_6f9a4c2b8d1e3a90
        object:
          type: string
          enum:
            - asset
        asset_type:
          type: string
          enum:
            - image
            - video
            - audio
        name:
          type: string
        status:
          type: string
          enum:
            - processing
            - active
            - failed
            - disabled
          description: |
            素材状态：`processing`（处理中，不可用于生成）、`active`（可用）、
            `failed`（处理失败）、`disabled`（已禁用）。
        resource_url:
          type: string
          format: uri
          description: >-
            平台保存后的素材访问地址，通常为平台 CDN 地址；仅在列表接口传入 `include_resource_url=1`
            且素材类型为图片或视频时返回。
        created_at:
          type: integer
        updated_at:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: model_endpoint_mismatch
            message:
              type: string
              example: 该模型不支持当前 endpoint。
  responses:
    Unauthorized:
      description: API Key 缺失或无效。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      x-default: sk-your-api-key

````