> ## 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.

# 查询素材详情

> 查询单个素材状态。`id` 为创建素材返回的 `asset_xxx`，不要带 `asset://` 前缀。

查询单个素材的状态和详细信息。

```
GET /v1/assets/{id}
Authorization: Bearer <API_KEY>
```

`id` 为创建素材返回的 `asset_xxx`，**不要带 `asset://` 前缀**。

通常用于轮询素材处理状态，等待 `status=active` 后再提交视频生成任务。

***

## 示例

```bash theme={null}
curl "https://{your-domain}/v1/assets/asset_6f9a4c2b8d1e3a90" \
  -H "Authorization: Bearer $API_KEY"
```

**处理中响应：**

```json theme={null}
{
  "id": "asset_6f9a4c2b8d1e3a90",
  "uri": "asset://asset_6f9a4c2b8d1e3a90",
  "object": "asset",
  "asset_type": "image",
  "name": "avatar-reference",
  "status": "processing",
  "created_at": 1779782400,
  "updated_at": 1779782400
}
```

**可用响应（`status=active`，可用于视频生成）：**

```json theme={null}
{
  "id": "asset_6f9a4c2b8d1e3a90",
  "uri": "asset://asset_6f9a4c2b8d1e3a90",
  "object": "asset",
  "asset_type": "image",
  "name": "avatar-reference",
  "status": "active",
  "created_at": 1779782400,
  "updated_at": 1779782460
}
```

## 素材状态

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

## 错误码

| HTTP 状态码 | `error.type`      | 场景                            |
| -------- | ----------------- | ----------------------------- |
| 404      | `asset_not_found` | 素材不存在、不属于当前用户/域名，或传入了无效素材 ID。 |


## OpenAPI

````yaml GET /v1/assets/{id}
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/{id}:
    get:
      tags:
        - videos
      summary: 查询素材详情
      description: 查询单个素材状态。`id` 为创建素材返回的 `asset_xxx`，不要带 `asset://` 前缀。
      operationId: getAsset
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: 素材 ID，格式为 `asset_xxx`，不带 `asset://` 前缀。
      responses:
        '200':
          description: 素材详情。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
              examples:
                active:
                  value:
                    id: asset_6f9a4c2b8d1e3a90
                    uri: asset://asset_6f9a4c2b8d1e3a90
                    object: asset
                    asset_type: image
                    name: avatar-reference
                    status: active
                    created_at: 1779782400
                    updated_at: 1779782460
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    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'
    NotFound:
      description: 资源不存在。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      x-default: sk-your-api-key

````