# 素材库 (/docs/api/native/media/libraries)



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

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

## 创建库 [#创建库]

`POST /media/v1/libraries`

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| models | MediaModelsInput | 否 | 各角色的模型调用 ID；局部更新，null 恢复默认 |
| name | string | 是 | 名称，1–64 个字符；允许重名 |
| labels | object | 否 | 标签对象；GET 时传 JSON 字符串；PATCH 整体替换，传 {} 清空 |
| understanding | object | 否 | 视觉、转写与语义理解开关 |

返回: `Library`.

### 响应 [#响应]

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| search | object | Search capabilities of this library’s embedding model. |
| search.image | boolean | Whether this library’s embedding model supports image-based visual search. |
| models | object | Resolved model call IDs used for new uploads and reprocessing. |
| models.vision | string | Model call ID for visual descriptions; the model must support image input. |
| models.embedding | string | Model call ID for search embeddings; must produce compatible vectors and cannot change while assets exist. |
| models.transcription | string | Model call ID for speech transcription. |
| id | string | Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters. |
| name | string | Display name of the library; duplicate names are allowed. |
| labels | object | Caller-defined string labels used to organize and filter libraries. |
| status | string | Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure. |
| asset_count | number | Number of assets currently stored in the library. |
| bytes | number | Total source-content size of the library’s assets, in bytes. |
| understanding | object | Settings controlling understanding tasks for new uploads. |
| understanding.visual | boolean | Enable captions, tags and OCR for images and video frames. |
| understanding.transcript | boolean | Enable speech transcription for audio and video soundtracks. |
| understanding.embedding | boolean | Enable generation of vectors for semantic search. |
| created_at | string | Time the library was created, in UTC. |
| updated_at | string | Time library settings, lifecycle or usage were last updated, in UTC. |
| deleted_at | string | null | Time the library entered deleting, or null when active or restored. |
| purge_at | string | null | Scheduled purge time while the library is deleting; null for an active or restored library. |

```bash
curl -X POST "https://api.deepraxis.ai/media/v1/libraries" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"walk-lib-r1-MDP-1791733789929","labels":{"sample":"walk-lib-r1-MDP-1791733789929"}}'
```

HTTP 200

```json
{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "name": "walk-lib-r1-MDP-1791733789929",
  "labels": {
    "sample": "walk-lib-r1-MDP-1791733789929"
  },
  "status": "active",
  "asset_count": 0,
  "bytes": 0,
  "models": {
    "vision": "qwen3.8-flash",
    "embedding": "qwen3-vl-embedding",
    "transcription": "whisper-large-v3-turbo"
  },
  "search": {
    "image": true
  },
  "understanding": {
    "visual": true,
    "transcript": true,
    "embedding": true
  },
  "created_at": "2026-10-11T15:50:04.230Z",
  "updated_at": "2026-10-11T15:50:04.931Z",
  "deleted_at": null,
  "purge_at": null
}
```

## 列出库 [#列出库]

`GET /media/v1/libraries`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| cursor | query | string | 上一页的 next_cursor |
| limit | query | integer | 每页 1–200 条，默认 50 |
| labels | query | string | 标签对象；GET 时传 JSON 字符串；PATCH 整体替换，传 {} 清空 |
| status | query | active / deleting | 资源状态 |

返回: `LibraryPage`.

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data | array<object> | Libraries in this page, ordered by creation time descending. |
| data[].search | object | Search capabilities of this library’s embedding model. |
| data[].models | object | Resolved model call IDs used for new uploads and reprocessing. |
| data[].id | string | Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters. |
| data[].name | string | Display name of the library; duplicate names are allowed. |
| data[].labels | object | Caller-defined string labels used to organize and filter libraries. |
| data[].status | string | Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure. |
| data[].asset_count | number | Number of assets currently stored in the library. |
| data[].bytes | number | Total source-content size of the library’s assets, in bytes. |
| data[].understanding | object | Settings controlling understanding tasks for new uploads. |
| data[].created_at | string | Time the library was created, in UTC. |
| data[].updated_at | string | Time library settings, lifecycle or usage were last updated, in UTC. |
| data[].deleted_at | string | null | Time the library entered deleting, or null when active or restored. |
| data[].purge_at | string | null | Scheduled purge time while the library is deleting; null for an active or restored library. |
| next_cursor | string | null | Opaque token to pass as cursor to listLibraries; null means no further page. |

```bash
curl -X GET "https://api.deepraxis.ai/media/v1/libraries?labels=%7B%22sample%22%3A%22walk-lib-r1-MDP-1791733789929%22%7D" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

HTTP 200

```json
{
  "data": [
    {
      "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
      "name": "walk-lib-r1-MDP-1791733789929",
      "status": "active",
      "asset_count": 0,
      "bytes": 0,
      "created_at": "2026-10-11T15:50:04.230Z",
      "updated_at": "2026-10-11T15:50:04.931Z",
      "deleted_at": null,
      "purge_at": null,
      "search": {
        "image": true
      },
      "models": {
        "vision": "qwen3.8-flash",
        "embedding": "qwen3-vl-embedding",
        "transcription": "whisper-large-v3-turbo"
      },
      "labels": {
        "sample": "walk-lib-r1-MDP-1791733789929"
      },
      "understanding": {
        "visual": true,
        "transcript": true,
        "embedding": true
      }
    }
  ],
  "next_cursor": null
}
```

## 读取库 [#读取库]

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

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

返回: `Library`.

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| search | object | Search capabilities of this library’s embedding model. |
| search.image | boolean | Whether this library’s embedding model supports image-based visual search. |
| models | object | Resolved model call IDs used for new uploads and reprocessing. |
| models.vision | string | Model call ID for visual descriptions; the model must support image input. |
| models.embedding | string | Model call ID for search embeddings; must produce compatible vectors and cannot change while assets exist. |
| models.transcription | string | Model call ID for speech transcription. |
| id | string | Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters. |
| name | string | Display name of the library; duplicate names are allowed. |
| labels | object | Caller-defined string labels used to organize and filter libraries. |
| status | string | Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure. |
| asset_count | number | Number of assets currently stored in the library. |
| bytes | number | Total source-content size of the library’s assets, in bytes. |
| understanding | object | Settings controlling understanding tasks for new uploads. |
| understanding.visual | boolean | Enable captions, tags and OCR for images and video frames. |
| understanding.transcript | boolean | Enable speech transcription for audio and video soundtracks. |
| understanding.embedding | boolean | Enable generation of vectors for semantic search. |
| created_at | string | Time the library was created, in UTC. |
| updated_at | string | Time library settings, lifecycle or usage were last updated, in UTC. |
| deleted_at | string | null | Time the library entered deleting, or null when active or restored. |
| purge_at | string | null | Scheduled purge time while the library is deleting; null for an active or restored library. |

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

HTTP 200

```json
{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "name": "walk-lib-r1-MDP-1791733789929",
  "status": "active",
  "asset_count": 0,
  "bytes": 0,
  "created_at": "2026-10-11T15:50:04.230Z",
  "updated_at": "2026-10-11T15:50:04.931Z",
  "deleted_at": null,
  "purge_at": null,
  "search": {
    "image": true
  },
  "models": {
    "vision": "qwen3.8-flash",
    "embedding": "qwen3-vl-embedding",
    "transcription": "whisper-large-v3-turbo"
  },
  "labels": {
    "sample": "walk-lib-r1-MDP-1791733789929"
  },
  "understanding": {
    "visual": true,
    "transcript": true,
    "embedding": true
  }
}
```

## 更新库 [#更新库]

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

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

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| models | MediaModelsInput | 否 | 各角色的模型调用 ID；局部更新，null 恢复默认 |
| name | string | 否 | 名称，1–64 个字符；允许重名 |
| labels | object | 否 | 标签对象；GET 时传 JSON 字符串；PATCH 整体替换，传 {} 清空 |
| understanding | object | 否 | 视觉、转写与语义理解开关 |

返回: `Library`.

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| search | object | Search capabilities of this library’s embedding model. |
| search.image | boolean | Whether this library’s embedding model supports image-based visual search. |
| models | object | Resolved model call IDs used for new uploads and reprocessing. |
| models.vision | string | Model call ID for visual descriptions; the model must support image input. |
| models.embedding | string | Model call ID for search embeddings; must produce compatible vectors and cannot change while assets exist. |
| models.transcription | string | Model call ID for speech transcription. |
| id | string | Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters. |
| name | string | Display name of the library; duplicate names are allowed. |
| labels | object | Caller-defined string labels used to organize and filter libraries. |
| status | string | Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure. |
| asset_count | number | Number of assets currently stored in the library. |
| bytes | number | Total source-content size of the library’s assets, in bytes. |
| understanding | object | Settings controlling understanding tasks for new uploads. |
| understanding.visual | boolean | Enable captions, tags and OCR for images and video frames. |
| understanding.transcript | boolean | Enable speech transcription for audio and video soundtracks. |
| understanding.embedding | boolean | Enable generation of vectors for semantic search. |
| created_at | string | Time the library was created, in UTC. |
| updated_at | string | Time library settings, lifecycle or usage were last updated, in UTC. |
| deleted_at | string | null | Time the library entered deleting, or null when active or restored. |
| purge_at | string | null | Scheduled purge time while the library is deleting; null for an active or restored library. |

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

HTTP 200

```json
{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "name": "walk-lib-r1-MDP-1791733789929-updated",
  "status": "active",
  "asset_count": 0,
  "bytes": 0,
  "created_at": "2026-10-11T15:50:04.230Z",
  "updated_at": "2026-10-11T15:50:07.147Z",
  "deleted_at": null,
  "purge_at": null,
  "search": {
    "image": true
  },
  "models": {
    "vision": "qwen3.8-flash",
    "embedding": "qwen3-vl-embedding",
    "transcription": "whisper-large-v3-turbo"
  },
  "labels": {
    "sample": "walk-lib-r1-MDP-1791733789929"
  },
  "understanding": {
    "visual": true,
    "transcript": true,
    "embedding": true
  }
}
```

## 删除库 [#删除库]

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

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

返回: `Library`.

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| search | object | Search capabilities of this library’s embedding model. |
| search.image | boolean | Whether this library’s embedding model supports image-based visual search. |
| models | object | Resolved model call IDs used for new uploads and reprocessing. |
| models.vision | string | Model call ID for visual descriptions; the model must support image input. |
| models.embedding | string | Model call ID for search embeddings; must produce compatible vectors and cannot change while assets exist. |
| models.transcription | string | Model call ID for speech transcription. |
| id | string | Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters. |
| name | string | Display name of the library; duplicate names are allowed. |
| labels | object | Caller-defined string labels used to organize and filter libraries. |
| status | string | Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure. |
| asset_count | number | Number of assets currently stored in the library. |
| bytes | number | Total source-content size of the library’s assets, in bytes. |
| understanding | object | Settings controlling understanding tasks for new uploads. |
| understanding.visual | boolean | Enable captions, tags and OCR for images and video frames. |
| understanding.transcript | boolean | Enable speech transcription for audio and video soundtracks. |
| understanding.embedding | boolean | Enable generation of vectors for semantic search. |
| created_at | string | Time the library was created, in UTC. |
| updated_at | string | Time library settings, lifecycle or usage were last updated, in UTC. |
| deleted_at | string | null | Time the library entered deleting, or null when active or restored. |
| purge_at | string | null | Scheduled purge time while the library is deleting; null for an active or restored library. |

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

HTTP 200

```json
{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "name": "walk-lib-r1-MDP-1791733789929-updated",
  "status": "deleting",
  "asset_count": 2,
  "bytes": 140,
  "created_at": "2026-10-11T15:50:04.230Z",
  "updated_at": "2026-10-11T15:50:30.664Z",
  "deleted_at": "2026-10-11T15:50:30.664Z",
  "purge_at": "2026-10-18T15:50:30.664Z",
  "search": {
    "image": true
  },
  "models": {
    "vision": "qwen3.8-flash",
    "embedding": "qwen3-vl-embedding",
    "transcription": "whisper-large-v3-turbo"
  },
  "labels": {
    "sample": "walk-lib-r1-MDP-1791733789929"
  },
  "understanding": {
    "visual": true,
    "transcript": true,
    "embedding": true
  }
}
```

## 恢复库 [#恢复库]

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

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

返回: `Library`.

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| search | object | Search capabilities of this library’s embedding model. |
| search.image | boolean | Whether this library’s embedding model supports image-based visual search. |
| models | object | Resolved model call IDs used for new uploads and reprocessing. |
| models.vision | string | Model call ID for visual descriptions; the model must support image input. |
| models.embedding | string | Model call ID for search embeddings; must produce compatible vectors and cannot change while assets exist. |
| models.transcription | string | Model call ID for speech transcription. |
| id | string | Generated library identifier: lib_ followed by 32 lowercase hexadecimal characters. |
| name | string | Display name of the library; duplicate names are allowed. |
| labels | object | Caller-defined string labels used to organize and filter libraries. |
| status | string | Library lifecycle: provisioning initializes the library; active permits asset operations; deleting awaits purge and may be restored before purge_at; deleted has been purged; failed indicates initialization failure. |
| asset_count | number | Number of assets currently stored in the library. |
| bytes | number | Total source-content size of the library’s assets, in bytes. |
| understanding | object | Settings controlling understanding tasks for new uploads. |
| understanding.visual | boolean | Enable captions, tags and OCR for images and video frames. |
| understanding.transcript | boolean | Enable speech transcription for audio and video soundtracks. |
| understanding.embedding | boolean | Enable generation of vectors for semantic search. |
| created_at | string | Time the library was created, in UTC. |
| updated_at | string | Time library settings, lifecycle or usage were last updated, in UTC. |
| deleted_at | string | null | Time the library entered deleting, or null when active or restored. |
| purge_at | string | null | Scheduled purge time while the library is deleting; null for an active or restored library. |

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

HTTP 200

```json
{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "name": "walk-lib-r1-MDP-1791733789929-updated",
  "status": "active",
  "asset_count": 2,
  "bytes": 140,
  "created_at": "2026-10-11T15:50:04.230Z",
  "updated_at": "2026-10-11T15:50:31.379Z",
  "deleted_at": null,
  "purge_at": null,
  "search": {
    "image": true
  },
  "models": {
    "vision": "qwen3.8-flash",
    "embedding": "qwen3-vl-embedding",
    "transcription": "whisper-large-v3-turbo"
  },
  "labels": {
    "sample": "walk-lib-r1-MDP-1791733789929"
  },
  "understanding": {
    "visual": true,
    "transcript": true,
    "embedding": true
  }
}
```

## 立即清除库 [#立即清除库]

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

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

返回: `PurgedLibrary`.

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| id | string | Identifier of the library that was permanently purged. |
| object | string | Resource discriminator identifying a library receipt. |
| purged | boolean | True when permanent library cleanup has completed. |

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

HTTP 200

```json
{
  "id": "lib_d3881a2f54a34cd79121b9d659e8378c",
  "object": "library",
  "purged": true
}
```

## Library [#library]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| search | object | 是 | 检索能力；search.image 为 true 时支持以图搜图 |
| models | MediaModels | 是 | 各角色的模型调用 ID；局部更新，null 恢复默认 |
| id | LibraryId | 是 | 资源 ID |
| name | string | 是 | 名称，1–64 个字符；允许重名 |
| labels | object | 是 | 标签对象；GET 时传 JSON 字符串；PATCH 整体替换，传 {} 清空 |
| status | LibraryStatus | 是 | 资源状态 |
| asset_count | number | 是 | 素材数量 |
| bytes | number | 是 | 文件字节数 |
| understanding | UnderstandingSettings | 是 | 视觉、转写与语义理解开关 |
| created_at | IsoTimestamp | 是 | 创建时间 |
| updated_at | IsoTimestamp | 是 | 更新时间 |
| deleted_at | IsoTimestamp / null | 是 | 删除时间；未删除为 null |
| purge_at | IsoTimestamp / null | 是 | 恢复截止时间 |

## LibraryPage [#librarypage]

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

## PurgedLibrary [#purgedlibrary]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| id | LibraryId | 是 | 资源 ID |
| object | "library" | 是 | — |
| purged | true | 是 | — |

## Page [#page]

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

## UnderstandingSettings [#understandingsettings]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| visual | boolean | 是 | 视觉理解开关 |
| transcript | boolean | 是 | 转写开关 |
| embedding | boolean | 是 | 语义理解开关 |

## 模型角色 [#模型角色]

`models` 指定三个角色使用的模型调用 ID（callModelId）。创建库时省略它会使用下表默认值；更新时只改传入的角色，未传的角色保持不变。某个角色传 `null` 恢复该角色默认值，`models: null` 恢复全部默认值。

| 角色 | 用途 | 默认值 |
| --- | --- | --- |
| vision | 图片与视频帧的视觉理解 | `qwen3.8-flash` |
| embedding | 将内容和检索查询生成向量，用于语义检索 | `qwen3-vl-embedding` |
| transcription | 音频转写 | `whisper-large-v3-turbo` |

写入时查询模型目录，校验传入的模型调用 ID。模型不存在返回 400 `INVALID_PARAMS`，消息为 `Model <id> is not available`；目录查询失败返回 502 `UPSTREAM_FAILED`。vision 必须支持图片输入，否则返回 400 `INVALID_PARAMS`。未知角色、空白 ID 或不合法的值也返回 400。

库中已有素材时不能更换 embedding，返回 409 `LIBRARY_INVALID_STATE`，消息为「库中已有素材时不能更换嵌入模型」。同一个向量空间必须由同一个模型生成，才能比较已有素材与查询向量；恢复默认值如果改变了 embedding，也受此限制。

修改 vision 或 transcription 只对新上传或重新处理（reprocess）的素材生效，不会自动重跑已有素材。reprocess 不带 kinds 时只重试失败项；显式指定 kinds 时，会强制重跑所选的已成功、失败或不支持项并替换结果。例如，修改 vision 后传入 `{ kinds: ["visual"] }`，修改 transcription 后传入 `{ kinds: ["transcript"] }`。

以下 PATCH 只将 vision 恢复默认，保留其他角色：

```bash
curl -X PATCH "https://api.deepraxis.ai/media/v1/libraries/${LIBRARY_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"models":{"vision":null}}'
```

新建库默认使用 qwen3-vl-embedding，支持以图搜图；旧库保留 bge-m3。只读字段 `search.image` 表示当前库是否支持以图搜图。选择其他模型时，会验证它能否输出 1024 维向量；无法输出则返回 INVALID\_PARAMS，探测不可用或缺少调用者身份返回 UPSTREAM\_FAILED。