# 素材 (/docs/api/native/media/assets)



[指南 →](/docs/cloud/services/media/quickstart)

[基础地址与鉴权](/docs/api/native/media)

## 列出素材 [#列出素材]

`GET /media/v1/libraries/{library_id}/assets`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| asset_folder | query | string | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| resource_type | query | image / video / raw | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| cursor | query | string | 上一页的 next_cursor |
| limit | query | integer | 每页 1–200 条，默认 50 |

返回: `AssetPage`.

### 响应 [#响应]

#### HTTP 200 [#http-200]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | Assets in this page, ordered by creation time descending. |
| data[].asset_id | string | Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites. |
| data[].public_id | string | Delivery identifier unique within this library, used in asset URLs. |
| data[].display_name | string | Human-readable asset name, independent of its delivery identifier. |
| data[].asset_folder | string | Organizational folder path; the empty string denotes the root folder. |
| data[].resource_type | string | Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection. |
| data[].type | string | Public asset delivery mode; upload is the only supported value. |
| data[].format | string | Detected file format used as the delivery URL extension. |
| data[].version | number | Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite. |
| data[].version_id | string | Identifier for this asset version, regenerated on overwrite. |
| data[].bytes | number | Size of the original source content, in bytes. |
| data[].etag | string | MD5 digest of the source bytes, as 32 lowercase hexadecimal characters. |
| data[].width | number | Source image or video width in pixels, when known. |
| data[].height | number | Source image or video height in pixels, when known. |
| data[].duration | number | Source audio or video duration in seconds, when known. |
| data[].pages | number |  |
| data[].is_audio | boolean | True for audio-only media, which uses resource_type video. |
| data[].original_filename | string | Original or overridden source filename with its final extension removed. |
| data[].tags | array<string> | Labels attached to the asset. |
| data[].context | object | Custom string metadata; omitted when empty or excluded by the search projection. |
| data[].created_at | string | Time this asset identity was created, in UTC. |
| data[].url | string | URL for retrieving this version of the asset’s original content. |
| data[].secure_url | string | HTTPS delivery URL for this asset version; equal to url. |
| data[].placeholder | boolean | False because this response represents stored source content. |
| data[].existing | boolean |  |
| data[].processing | object | Progress of understanding and embedding tasks for the asset. |
| data[].library_id | string | Identifier of the library containing this asset. |
| data[].sha256 | string | SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters. |
| data[].status | string | Resource status; active identifies an asset that has not been deleted. |
| data[].semantic | string | Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending. |
| data[].preview | object | Generated video previews, present once preview generation succeeds. |
| next_cursor | string | null | Opaque token to pass as cursor to listAssets; null means no further page. |

```bash
curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

HTTP 200

```json
{
  "data": [
    {
      "asset_id": "9dfa312ef9bc4b00816339b598b1152c",
      "public_id": "walk-lib-r1-MDP-1791733789929-tagged",
      "display_name": "walk-lib-r1-MDP-1791733789929-tagged",
      "asset_folder": "",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791733815,
      "version_id": "26cb8171caa5431b8373ad417fd71e32",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "tags": [
        "docs"
      ],
      "processing": {
        "state": "processing",
        "kinds": {
          "embedding": "pending",
          "visual": "running",
          "tagging": "running"
        },
        "updated_at": "2026-10-11T15:50:17.571Z"
      },
      "created_at": "2026-10-11T15:50:15.996Z",
      "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
      "placeholder": false,
      "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
      "sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
      "status": "active",
      "semantic": "pending"
    },
    {
      "asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
      "public_id": "walk-lib-r1-MDP-1791733789929-plain",
      "display_name": "walk-lib-r1-MDP-1791733789929-plain",
      "asset_folder": "",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791733810,
      "version_id": "fdf3c8cd40c2424d86e8397425a69857",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "tags": [
        "docs"
      ],
      "created_at": "2026-10-11T15:50:10.842Z",
      "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
      "placeholder": false,
      "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
      "sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
      "status": "active",
      "processing": {
        "state": "processing",
        "kinds": {
          "embedding": "pending",
          "visual": "running"
        },
        "updated_at": "2026-10-11T15:50:17.571Z"
      },
      "semantic": "pending"
    }
  ],
  "next_cursor": null
}
```

## 上传素材 [#上传素材]

`POST /media/v1/libraries/{library_id}/assets`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| X-Unique-Upload-Id | header | string | — |
| Content-Range | header | string | — |

### 请求体 [#请求体]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| file | string / string | 是 | 文件字节、HTTPS URL、data URI 或同账户 file_… |
| public_id | string | 否 | 交付地址中的素材名称，可带路径 |
| public_id_prefix | string | 否 | public_id 的路径前缀；末尾的 / 可有可无，前缀与 ID 之间只保留一个 / |
| display_name | string | 否 | 显示名称 |
| asset_folder | string | 否 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| use_filename | boolean | 否 | 用文件名生成 public_id |
| unique_filename | boolean | 否 | 自动附加唯一后缀 |
| use_filename_as_display_name | boolean | 否 | 用文件名作为显示名称 |
| filename_override | string | 否 | 覆盖原文件名称 |
| overwrite | boolean | 否 | 是否覆盖同名素材 |
| tags | string / string[] | 否 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | string / object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| auto_tagging | number | 否 | 理解后将达到阈值的标签合并；0–1 |
| resource_type | image / video / raw / auto | 否 | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |

返回: `CloudinaryResource`.

### 响应 [#响应-1]

#### HTTP 200 [#http-200-1]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites. |
| public_id | string | Delivery identifier unique within this library, used in asset URLs. |
| display_name | string | Human-readable asset name, independent of its delivery identifier. |
| asset_folder | string | Organizational folder path; the empty string denotes the root folder. |
| resource_type | string | Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection. |
| type | string | Public asset delivery mode; upload is the only supported value. |
| format | string | Detected file format used as the delivery URL extension. |
| version | number | Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite. |
| version_id | string | Identifier for this asset version, regenerated on overwrite. |
| bytes | number | Size of the original source content, in bytes. |
| etag | string | MD5 digest of the source bytes, as 32 lowercase hexadecimal characters. |
| width | number | Source image or video width in pixels, when known. |
| height | number | Source image or video height in pixels, when known. |
| duration | number | Source audio or video duration in seconds, when known. |
| pages | number |  |
| is_audio | boolean | True for audio-only media, which uses resource_type video. |
| original_filename | string | Original or overridden source filename with its final extension removed. |
| tags | array<string> | Labels attached to the asset. |
| context | object | Custom string metadata; omitted when empty or excluded by the search projection. |
| context.custom | object | Caller-supplied metadata entries with string values. |
| created_at | string | Time this asset identity was created, in UTC. |
| url | string | URL for retrieving this version of the asset’s original content. |
| secure_url | string | HTTPS delivery URL for this asset version; equal to url. |
| placeholder | boolean | False because this response represents stored source content. |
| existing | boolean | True when overwrite=false returns the asset already stored under the requested public_id. |
| processing | object | Processing progress, included when auto_tagging was requested. |
| processing.state | string |  |
| processing.kinds | object | Processing states by kind. tagging is present when auto_tagging was requested and follows visual understanding. |
| processing.updated_at | string | Time the processing state was last updated, in UTC. |
| done | boolean | False while more chunks are needed before the asset is complete. / True when the final chunk has completed the asset upload. |
| upload_id | string | Upload session identifier supplied in X-Unique-Upload-Id; reuse it for subsequent chunks. |

```bash
curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"file":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==","public_id":"walk-lib-r1-MDP-1791733789929-tagged","tags":["docs"],"auto_tagging":0.6}'
```

HTTP 200

```json
{
  "asset_id": "9dfa312ef9bc4b00816339b598b1152c",
  "public_id": "walk-lib-r1-MDP-1791733789929-tagged",
  "display_name": "walk-lib-r1-MDP-1791733789929-tagged",
  "asset_folder": "",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791733815,
  "version_id": "26cb8171caa5431b8373ad417fd71e32",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "processing": {
    "state": "pending",
    "kinds": {
      "visual": "pending",
      "embedding": "pending",
      "tagging": "pending"
    },
    "updated_at": "2026-10-11T15:50:15.996Z"
  },
  "created_at": "2026-10-11T15:50:15.996Z",
  "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733815/walk-lib-r1-MDP-1791733789929-tagged.png",
  "placeholder": false
}
```

## 导入文件 [#导入文件]

`POST /media/v1/libraries/{library_id}/assets/import`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |

### 请求体 [#请求体-1]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| file_id | string | 是 | 同账户文件 ID |
| public_id | string | 否 | 交付地址中的素材名称，可带路径 |
| public_id_prefix | string | 否 | public_id 的路径前缀；末尾的 / 可有可无，前缀与 ID 之间只保留一个 / |
| display_name | string | 否 | 显示名称 |
| asset_folder | string | 否 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| use_filename | boolean | 否 | 用文件名生成 public_id |
| unique_filename | boolean | 否 | 自动附加唯一后缀 |
| use_filename_as_display_name | boolean | 否 | 用文件名作为显示名称 |
| filename_override | string | 否 | 覆盖原文件名称 |
| overwrite | boolean | 否 | 是否覆盖同名素材 |
| tags | string / string[] | 否 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | string / object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| auto_tagging | number | 否 | 理解后将达到阈值的标签合并；0–1 |
| resource_type | image / video / raw / auto | 否 | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |

返回: `Asset`.

### 响应 [#响应-2]

#### HTTP 200 [#http-200-2]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites. |
| public_id | string | Delivery identifier unique within this library, used in asset URLs. |
| display_name | string | Human-readable asset name, independent of its delivery identifier. |
| asset_folder | string | Organizational folder path; the empty string denotes the root folder. |
| resource_type | string | Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection. |
| type | string | Public asset delivery mode; upload is the only supported value. |
| format | string | Detected file format used as the delivery URL extension. |
| version | number | Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite. |
| version_id | string | Identifier for this asset version, regenerated on overwrite. |
| bytes | number | Size of the original source content, in bytes. |
| etag | string | MD5 digest of the source bytes, as 32 lowercase hexadecimal characters. |
| width | number | Source image or video width in pixels, when known. |
| height | number | Source image or video height in pixels, when known. |
| duration | number | Source audio or video duration in seconds, when known. |
| pages | number |  |
| is_audio | boolean | True for audio-only media, which uses resource_type video. |
| original_filename | string | Original or overridden source filename with its final extension removed. |
| tags | array<string> | Labels attached to the asset. |
| context | object | Custom string metadata; omitted when empty or excluded by the search projection. |
| context.custom | object | Caller-supplied metadata entries with string values. |
| created_at | string | Time this asset identity was created, in UTC. |
| url | string | URL for retrieving this version of the asset’s original content. |
| secure_url | string | HTTPS delivery URL for this asset version; equal to url. |
| placeholder | boolean | False because this response represents stored source content. |
| existing | boolean |  |
| processing | object | Progress of understanding and embedding tasks for the asset. |
| processing.state | string |  |
| processing.kinds | object | Processing states by kind. tagging is present when auto_tagging was requested and follows visual understanding. |
| processing.updated_at | string | Time the processing state was last updated, in UTC. |
| library_id | string | Identifier of the library containing this asset. |
| sha256 | string | SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters. |
| status | string | Resource status; active identifies an asset that has not been deleted. |
| semantic | string | Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending. |
| preview | object | Generated video previews, present once preview generation succeeds. |
| preview.poster_url | string | Delivery URL of the video’s first-frame poster. |
| preview.storyboard | object | Preview sprite sheet with tile dimensions and sample spacing. |

## 读取素材 [#读取素材]

`GET /media/v1/libraries/{library_id}/assets/{asset_id}`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| asset_id | path | string | 素材 ID |

返回: `Asset`.

### 响应 [#响应-3]

#### HTTP 200 [#http-200-3]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites. |
| public_id | string | Delivery identifier unique within this library, used in asset URLs. |
| display_name | string | Human-readable asset name, independent of its delivery identifier. |
| asset_folder | string | Organizational folder path; the empty string denotes the root folder. |
| resource_type | string | Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection. |
| type | string | Public asset delivery mode; upload is the only supported value. |
| format | string | Detected file format used as the delivery URL extension. |
| version | number | Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite. |
| version_id | string | Identifier for this asset version, regenerated on overwrite. |
| bytes | number | Size of the original source content, in bytes. |
| etag | string | MD5 digest of the source bytes, as 32 lowercase hexadecimal characters. |
| width | number | Source image or video width in pixels, when known. |
| height | number | Source image or video height in pixels, when known. |
| duration | number | Source audio or video duration in seconds, when known. |
| pages | number |  |
| is_audio | boolean | True for audio-only media, which uses resource_type video. |
| original_filename | string | Original or overridden source filename with its final extension removed. |
| tags | array<string> | Labels attached to the asset. |
| context | object | Custom string metadata; omitted when empty or excluded by the search projection. |
| context.custom | object | Caller-supplied metadata entries with string values. |
| created_at | string | Time this asset identity was created, in UTC. |
| url | string | URL for retrieving this version of the asset’s original content. |
| secure_url | string | HTTPS delivery URL for this asset version; equal to url. |
| placeholder | boolean | False because this response represents stored source content. |
| existing | boolean |  |
| processing | object | Progress of understanding and embedding tasks for the asset. |
| processing.state | string |  |
| processing.kinds | object | Processing states by kind. tagging is present when auto_tagging was requested and follows visual understanding. |
| processing.updated_at | string | Time the processing state was last updated, in UTC. |
| library_id | string | Identifier of the library containing this asset. |
| sha256 | string | SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters. |
| status | string | Resource status; active identifies an asset that has not been deleted. |
| semantic | string | Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending. |
| preview | object | Generated video previews, present once preview generation succeeds. |
| preview.poster_url | string | Delivery URL of the video’s first-frame poster. |
| preview.storyboard | object | Preview sprite sheet with tile dimensions and sample spacing. |

```bash
curl -X GET "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets/85b7ef616a8b4719a41777a036ebc1d2" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

HTTP 200

```json
{
  "asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
  "public_id": "walk-lib-r1-MDP-1791733789929-plain",
  "display_name": "walk-lib-r1-MDP-1791733789929-plain",
  "asset_folder": "",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791733810,
  "version_id": "fdf3c8cd40c2424d86e8397425a69857",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "created_at": "2026-10-11T15:50:10.842Z",
  "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "placeholder": false,
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
  "status": "active",
  "processing": {
    "state": "processing",
    "kinds": {
      "embedding": "pending",
      "visual": "running"
    },
    "updated_at": "2026-10-11T15:50:17.571Z"
  },
  "semantic": "pending"
}
```

## 更新素材 [#更新素材]

`PATCH /media/v1/libraries/{library_id}/assets/{asset_id}`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| asset_id | path | string | 素材 ID |

### 请求体 [#请求体-2]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| display_name | string | 否 | 显示名称 |
| asset_folder | string | 否 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| tags | string[] | 否 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |

返回: `Asset`.

### 响应 [#响应-4]

#### HTTP 200 [#http-200-4]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites. |
| public_id | string | Delivery identifier unique within this library, used in asset URLs. |
| display_name | string | Human-readable asset name, independent of its delivery identifier. |
| asset_folder | string | Organizational folder path; the empty string denotes the root folder. |
| resource_type | string | Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection. |
| type | string | Public asset delivery mode; upload is the only supported value. |
| format | string | Detected file format used as the delivery URL extension. |
| version | number | Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite. |
| version_id | string | Identifier for this asset version, regenerated on overwrite. |
| bytes | number | Size of the original source content, in bytes. |
| etag | string | MD5 digest of the source bytes, as 32 lowercase hexadecimal characters. |
| width | number | Source image or video width in pixels, when known. |
| height | number | Source image or video height in pixels, when known. |
| duration | number | Source audio or video duration in seconds, when known. |
| pages | number |  |
| is_audio | boolean | True for audio-only media, which uses resource_type video. |
| original_filename | string | Original or overridden source filename with its final extension removed. |
| tags | array<string> | Labels attached to the asset. |
| context | object | Custom string metadata; omitted when empty or excluded by the search projection. |
| context.custom | object | Caller-supplied metadata entries with string values. |
| created_at | string | Time this asset identity was created, in UTC. |
| url | string | URL for retrieving this version of the asset’s original content. |
| secure_url | string | HTTPS delivery URL for this asset version; equal to url. |
| placeholder | boolean | False because this response represents stored source content. |
| existing | boolean |  |
| processing | object | Progress of understanding and embedding tasks for the asset. |
| processing.state | string |  |
| processing.kinds | object | Processing states by kind. tagging is present when auto_tagging was requested and follows visual understanding. |
| processing.updated_at | string | Time the processing state was last updated, in UTC. |
| library_id | string | Identifier of the library containing this asset. |
| sha256 | string | SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters. |
| status | string | Resource status; active identifies an asset that has not been deleted. |
| semantic | string | Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending. |
| preview | object | Generated video previews, present once preview generation succeeds. |
| preview.poster_url | string | Delivery URL of the video’s first-frame poster. |
| preview.storyboard | object | Preview sprite sheet with tile dimensions and sample spacing. |

```bash
curl -X PATCH "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets/85b7ef616a8b4719a41777a036ebc1d2" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"display_name":"walk-lib-r1-MDP-1791733789929-plain"}'
```

HTTP 200

```json
{
  "asset_id": "85b7ef616a8b4719a41777a036ebc1d2",
  "public_id": "walk-lib-r1-MDP-1791733789929-plain",
  "display_name": "walk-lib-r1-MDP-1791733789929-plain",
  "asset_folder": "",
  "resource_type": "image",
  "type": "upload",
  "format": "png",
  "version": 1791733810,
  "version_id": "fdf3c8cd40c2424d86e8397425a69857",
  "bytes": 70,
  "etag": "b357a19c87624c7c4d131aeeb4ae677f",
  "width": 1,
  "height": 1,
  "original_filename": "file",
  "tags": [
    "docs"
  ],
  "created_at": "2026-10-11T15:50:10.842Z",
  "url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "secure_url": "https://media-develop.praxisusercontent.com/lib_d3881a2f54a34cd79121b9d659e8378c/image/upload/v1791733810/walk-lib-r1-MDP-1791733789929-plain.png",
  "placeholder": false,
  "library_id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "sha256": "497790947d4666760ce38f3c00e852c71fdb66cae849bae8e9ede352719e1581",
  "status": "active",
  "processing": {
    "state": "processing",
    "kinds": {
      "embedding": "pending",
      "visual": "running"
    },
    "updated_at": "2026-10-11T15:50:17.571Z"
  },
  "semantic": "pending"
}
```

## 删除素材 [#删除素材]

`DELETE /media/v1/libraries/{library_id}/assets/{asset_id}`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| asset_id | path | string | 素材 ID |

返回: `Deleted`.

### 响应 [#响应-5]

#### HTTP 200 [#http-200-5]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| deleted | boolean | True once this asset has been removed from the library. |

```bash
curl -X DELETE "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets/e5f3de0d8609482d8b351894b133c8cb" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

HTTP 200

```json
{
  "deleted": true
}
```

## 重新处理素材 [#重新处理素材]

`POST /media/v1/libraries/{library_id}/assets/{asset_id}/reprocess`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| asset_id | path | string | 素材 ID |

### 请求体 [#请求体-3]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| kinds | ProcessingKind[] | 否 | 要强制重跑的处理种类；省略时只重试失败项 |

返回: `Asset`.

kinds 可选 visual、frames、transcript、embedding。不带 kinds 时，只重跑当前素材版本的失败任务。显式传 kinds 时，所选的 ready、failed、unsupported 任务会重置为 pending 并强制重跑；pending 或 running 任务原样跳过，重复请求不会重复入队。

kinds 必须适用于素材类型：图片为 visual、embedding；音频为 transcript、embedding；视频为 frames、visual、transcript、embedding；raw 没有可重跑的种类。全部不适用时返回 400 INVALID\_PARAMS，消息列出该素材可用的 kinds；部分适用时只处理适用的种类，其余忽略（返回的 Asset 没有字段说明被忽略的种类，请以 processing.kinds 为准）。

重跑 visual、frames 或 transcript 时，旧结果立即标记为 superseded，同时将 embedding 与素材的 semantic 置为 pending。旧向量继续服务语义检索，直到新的向量写入后才被替换，因此重新处理期间素材不会从检索结果中消失；期间命中片段可能显示素材名称而非旧描述。默认读取只返回当前结果；使用 include\_superseded=true 可查看历史。请求立即返回更新后的 Asset，处理异步完成。

```bash
curl -X POST "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}/assets/${ASSET_ID}/reprocess" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'
```

### 响应 [#响应-6]

#### HTTP 200 [#http-200-6]

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| asset_id | string | Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites. |
| public_id | string | Delivery identifier unique within this library, used in asset URLs. |
| display_name | string | Human-readable asset name, independent of its delivery identifier. |
| asset_folder | string | Organizational folder path; the empty string denotes the root folder. |
| resource_type | string | Stored media category: image for images, video for video or audio, and raw for other files. Upload also accepts auto for detection. |
| type | string | Public asset delivery mode; upload is the only supported value. |
| format | string | Detected file format used as the delivery URL extension. |
| version | number | Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite. |
| version_id | string | Identifier for this asset version, regenerated on overwrite. |
| bytes | number | Size of the original source content, in bytes. |
| etag | string | MD5 digest of the source bytes, as 32 lowercase hexadecimal characters. |
| width | number | Source image or video width in pixels, when known. |
| height | number | Source image or video height in pixels, when known. |
| duration | number | Source audio or video duration in seconds, when known. |
| pages | number |  |
| is_audio | boolean | True for audio-only media, which uses resource_type video. |
| original_filename | string | Original or overridden source filename with its final extension removed. |
| tags | array<string> | Labels attached to the asset. |
| context | object | Custom string metadata; omitted when empty or excluded by the search projection. |
| context.custom | object | Caller-supplied metadata entries with string values. |
| created_at | string | Time this asset identity was created, in UTC. |
| url | string | URL for retrieving this version of the asset’s original content. |
| secure_url | string | HTTPS delivery URL for this asset version; equal to url. |
| placeholder | boolean | False because this response represents stored source content. |
| existing | boolean |  |
| processing | object | Progress of understanding and embedding tasks for the asset. |
| processing.state | string |  |
| processing.kinds | object | Processing states by kind. tagging is present when auto_tagging was requested and follows visual understanding. |
| processing.updated_at | string | Time the processing state was last updated, in UTC. |
| library_id | string | Identifier of the library containing this asset. |
| sha256 | string | SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters. |
| status | string | Resource status; active identifies an asset that has not been deleted. |
| semantic | string | Search-vector status: pending awaits vector generation or reprocessing; ready has searchable vectors; unavailable indicates disabled, unsupported or failed embedding. Existing vectors may still serve searches while reprocessing is pending. |
| preview | object | Generated video previews, present once preview generation succeeds. |
| preview.poster_url | string | Delivery URL of the video’s first-frame poster. |
| preview.storyboard | object | Preview sprite sheet with tile dimensions and sample spacing. |

## AssetPage [#assetpage]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| data | Asset[] | 是 | 本页结果 |
| next_cursor | string / null | 是 | 下一页游标；没有时为 null 或省略 |

## CloudinaryResource [#cloudinaryresource]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| asset_id | AssetId | 是 | 素材 ID |
| public_id | string | 是 | 交付地址中的素材名称，可带路径 |
| display_name | string | 是 | 显示名称 |
| asset_folder | string | 是 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| resource_type | ResourceType | 是 | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| type | DeliveryType | 是 | 资源或事件类型 |
| format | string | 是 | 文件格式 |
| version | number | 是 | 交付版本号 |
| version_id | string | 是 | 版本标识 |
| bytes | number | 是 | 文件字节数 |
| etag | string | 是 | 文件校验标识 |
| width | number | 否 | 宽度像素 |
| height | number | 否 | 高度像素 |
| duration | number | 否 | 时长秒数 |
| pages | number | 否 | 文档页数 |
| is_audio | boolean | 否 | 是否为音频 |
| original_filename | string | 否 | 原文件名称 |
| tags | string[] | 是 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| created_at | IsoTimestamp | 是 | 创建时间 |
| url | string | 是 | 原文件地址 |
| secure_url | string | 是 | HTTPS 交付地址 |
| placeholder | false | 是 | 固定为 false |
| existing | boolean | 否 | 未覆盖时是否返回已有素材 |
| processing | Processing | 否 | 整体与各项理解状态 |

## Asset [#asset]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| asset_id | AssetId | 是 | 素材 ID |
| public_id | string | 是 | 交付地址中的素材名称，可带路径 |
| display_name | string | 是 | 显示名称 |
| asset_folder | string | 是 | 组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根 |
| resource_type | ResourceType | 是 | image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400 |
| type | DeliveryType | 是 | 资源或事件类型 |
| format | string | 是 | 文件格式 |
| version | number | 是 | 交付版本号 |
| version_id | string | 是 | 版本标识 |
| bytes | number | 是 | 文件字节数 |
| etag | string | 是 | 文件校验标识 |
| width | number | 否 | 宽度像素 |
| height | number | 否 | 高度像素 |
| duration | number | 否 | 时长秒数 |
| pages | number | 否 | 文档页数 |
| is_audio | boolean | 否 | 是否为音频 |
| original_filename | string | 否 | 原文件名称 |
| tags | string[] | 是 | 素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换 |
| context | object | 否 | 自定义文字键值；PATCH 整体替换，传 {} 清空 |
| created_at | IsoTimestamp | 是 | 创建时间 |
| url | string | 是 | 原文件地址 |
| secure_url | string | 是 | HTTPS 交付地址 |
| placeholder | false | 是 | 固定为 false |
| existing | boolean | 否 | 未覆盖时是否返回已有素材 |
| processing | Processing | 是 | 整体与各项理解状态 |
| library_id | LibraryId | 是 | 库 ID |
| sha256 | string | 是 | 内容校验摘要 |
| status | "active" | 是 | 资源状态 |
| semantic | "pending" / "ready" / "unavailable" | 是 | ready 时可语义检索 |
| preview | object | 否 | 预览海报和故事板 |

## Deleted [#deleted]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| deleted | true | 是 | 删除结果 |

## Processing [#processing]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| state | ProcessingState | 是 | 整体处理状态 |
| kinds | object | 是 | 各项处理状态 |
| updated_at | IsoTimestamp | 是 | 更新时间 |

## Storyboard [#storyboard]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| url | string | 是 | 原文件地址 |
| tiles | number | 是 | 故事板画面数 |
| interval_ms | number | 是 | 画面间隔毫秒数 |
| tile_width | number | 是 | 单个画面宽度 |
| tile_height | number | 是 | 单个画面高度 |