# 检索 (/docs/api/native/media/search)



expression 接受表达式；semantic 与 search 接受自然语言。语义检索只返回就绪素材。

[表达式语法](/docs/api/compatible/cloudinary/search)

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

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

## 表达式检索 [#表达式检索]

`POST /media/v1/libraries/{library_id}/search/expression`

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

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| expression | string | 否 | 结构化查询表达式；空表达式返回全部素材 |
| sort_by | object[] | 否 | 排序字段与方向 |
| max_results | integer | 否 | 最多 500；检索默认 100，Admin 默认 10 |
| next_cursor | string | 否 | 下一页游标；没有时为 null 或省略 |
| with_field | tags / context[] | 否 | 额外返回 tags 或 context |
| aggregate | AggregateField[] | 否 | 统计字段 |

返回: `ExpressionSearchResult`.

### 响应 [#响应]

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| total_count | number | Number of matching assets across pages; a lower bound when total_count_exact is false. |
| time | number | Elapsed search time in whole milliseconds. |
| next_cursor | string | Continuation token for the next page; omitted when no further page is available. |
| resources | array<object> | Assets in this page, ordered by sort_by; tags and context follow with_field. |
| resources[].asset_id | string | Generated asset identifier: 32 lowercase hexadecimal characters, preserved across overwrites. |
| resources[].public_id | string | Delivery identifier unique within this library, used in asset URLs. |
| resources[].display_name | string | Human-readable asset name, independent of its delivery identifier. |
| resources[].asset_folder | string | Organizational folder path; the empty string denotes the root folder. |
| resources[].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. |
| resources[].type | string | Public asset delivery mode; upload is the only supported value. |
| resources[].format | string | Detected file format used as the delivery URL extension. |
| resources[].version | number | Monotonically increasing asset version used in delivery URLs; based on upload time in Unix seconds and advanced on overwrite. |
| resources[].version_id | string | Identifier for this asset version, regenerated on overwrite. |
| resources[].bytes | number | Size of the original source content, in bytes. |
| resources[].etag | string | MD5 digest of the source bytes, as 32 lowercase hexadecimal characters. |
| resources[].width | number | Source image or video width in pixels, when known. |
| resources[].height | number | Source image or video height in pixels, when known. |
| resources[].duration | number | Source audio or video duration in seconds, when known. |
| resources[].pages | number |  |
| resources[].is_audio | boolean | True for audio-only media, which uses resource_type video. |
| resources[].original_filename | string | Original or overridden source filename with its final extension removed. |
| resources[].tags | array<string> | Labels attached to the asset. |
| resources[].context | object | Custom string metadata; omitted when empty or excluded by the search projection. |
| resources[].created_at | string | Time this asset identity was created, in UTC. |
| resources[].url | string | URL for retrieving this version of the asset’s original content. |
| resources[].secure_url | string | HTTPS delivery URL for this asset version; equal to url. |
| resources[].placeholder | boolean | False because this response represents stored source content. |
| resources[].existing | boolean |  |
| resources[].processing | object | Progress of understanding and embedding tasks for the asset. |
| resources[].library_id | string | Identifier of the library containing this asset. |
| resources[].sha256 | string | SHA-256 digest of the source bytes, as 64 lowercase hexadecimal characters. |
| resources[].status | string | Resource status; active identifies an asset that has not been deleted. |
| resources[].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. |
| resources[].preview | object | Generated video previews, present once preview generation succeeds. |
| aggregations | object | Requested facet counts, keyed by facet name and then by field value. |
| total_count_exact | boolean | Whether total_count covers all matches; false indicates a bounded partial count. |
| aggregations_exact | boolean | Whether the returned facet counts cover all matching assets. |

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

HTTP 200

```json
{
  "total_count": 2,
  "total_count_exact": true,
  "time": 0,
  "resources": [
    {
      "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",
      "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",
      "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"
    }
  ]
}
```

## 以图搜图 [#以图搜图]

`POST /media/v1/libraries/{library_id}/search/visual`

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

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| asset_id | AssetId | 否 | 素材 ID |
| image | object | 否 | 查询图片对象，data 为 base64，mime 为图片类型 |
| top_k | integer | 否 | 命中数，1–50 |
| filter | string | 否 | 表达式筛选条件 |

返回: `SemanticSearchResult`.

库的 `search.image` 为 true 时可用；不支持的库返回 LIBRARY\_INVALID\_STATE。图片仅接受 JPEG、PNG、WebP、GIF，解码后最大 10 MiB。每个素材返回最高分命中，视频定位到最佳帧。qwen3-vl-embedding 的图片相似度门槛为 0.35。标定来自 2026-10-10 的测试：同图变体 0.82–0.96，同类场景 0.38–0.66，无关图片最高 0.34。

`asset_id` 与 `image: { data, mime }` 必须且只能给一个。asset\_id 复用已有图片理解并排除素材自身；视频使用第一帧，未完成理解返回 LIBRARY\_INVALID\_STATE。上传图片的 data 为 base64。top\_k 默认 20，范围 1–50；filter 使用与 semantic 相同的表达式。仅检索图片相似内容，返回与 semantic 相同的 hits、embedding\_producer、not\_ready\_excluded；matches.kind 为 image，snippet 为最新描述或素材名称。删除、旧版本及已替换的理解不会出现在结果中。

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| hits | array<object> | Ranked assets up to top_k; an empty array means no eligible matches were found. |
| hits[].asset | object | Asset matched by the query. |
| hits[].score | number | Ranking score: cosine similarity for semantic or visual search; normalized rank-fusion score for hybrid search. Higher values rank first. |
| hits[].semantic_score | number | null | Cosine similarity for hybrid hits with a semantic match; null for keyword-only hybrid hits. Omitted outside hybrid mode. |
| hits[].matches | array<object> | Supporting content or metadata matches contributing to this asset’s hit. |
| embedding_producer | string | Embedding model identifier used for the query, or for the source asset embedding in an asset-based visual query. |
| not_ready_excluded | number | Number of distinct candidate asset identifiers, or unresolved vector identifiers, excluded because their vectors or assets were missing, deleted or stale; not a count of all pending assets in the library. |

## 语义检索 [#语义检索]

`POST /media/v1/libraries/{library_id}/search/semantic`

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

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| query | string | 是 | 用自然语言描述要找的内容 |
| filter | string | 否 | 表达式筛选条件 |
| top_k | integer | 否 | 命中数，1–50 |
| mode | hybrid / semantic | 否 | hybrid 结合关键词与语义；semantic 仅语义 |

返回: `SemanticSearchResult`.

使用 bge-m3 时，向量候选在与关键词结果融合前按余弦相似度 ≥ 0.55 筛选，新完成的内容也使用相同门槛。门槛依据 2026-10-09 的 7 个演示素材标定：相关结果最低约 0.58（0.581–0.729），不相关结果最高 0.523；完全无关的查询最高 0.478。qwen3-vl-embedding 的文字查询对文字内容（描述、转写）门槛为 0.40，对图片内容门槛为 0.25；其他模型尚未标定，暂不过滤。关键词命中不受此门槛影响。查询与库内容都不相关时返回空列表；mode=semantic 只返回达到向量门槛的结果。

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| hits | array<object> | Ranked assets up to top_k; an empty array means no eligible matches were found. |
| hits[].asset | object | Asset matched by the query. |
| hits[].score | number | Ranking score: cosine similarity for semantic or visual search; normalized rank-fusion score for hybrid search. Higher values rank first. |
| hits[].semantic_score | number | null | Cosine similarity for hybrid hits with a semantic match; null for keyword-only hybrid hits. Omitted outside hybrid mode. |
| hits[].matches | array<object> | Supporting content or metadata matches contributing to this asset’s hit. |
| embedding_producer | string | Embedding model identifier used for the query, or for the source asset embedding in an asset-based visual query. |
| not_ready_excluded | number | Number of distinct candidate asset identifiers, or unresolved vector identifiers, excluded because their vectors or assets were missing, deleted or stale; not a count of all pending assets in the library. |

## 语义检索别名 [#语义检索别名]

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

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

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| query | string | 是 | 用自然语言描述要找的内容 |
| filter | string | 否 | 表达式筛选条件 |
| top_k | integer | 否 | 命中数，1–50 |
| mode | hybrid / semantic | 否 | hybrid 结合关键词与语义；semantic 仅语义 |

返回: `SemanticSearchResult`.

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| hits | array<object> | Ranked assets up to top_k; an empty array means no eligible matches were found. |
| hits[].asset | object | Asset matched by the query. |
| hits[].score | number | Ranking score: cosine similarity for semantic or visual search; normalized rank-fusion score for hybrid search. Higher values rank first. |
| hits[].semantic_score | number | null | Cosine similarity for hybrid hits with a semantic match; null for keyword-only hybrid hits. Omitted outside hybrid mode. |
| hits[].matches | array<object> | Supporting content or metadata matches contributing to this asset’s hit. |
| embedding_producer | string | Embedding model identifier used for the query, or for the source asset embedding in an asset-based visual query. |
| not_ready_excluded | number | Number of distinct candidate asset identifiers, or unresolved vector identifiers, excluded because their vectors or assets were missing, deleted or stale; not a count of all pending assets in the library. |

## ExpressionSearchResult [#expressionsearchresult]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| total_count | number | 是 | 匹配总数 |
| time | number | 是 | 检索耗时，整数毫秒，由服务端测得 |
| next_cursor | string | 否 | 下一页游标；没有时为 null 或省略 |
| resources | SearchAsset[] | 是 | 本页素材 |
| aggregations | object | 否 | 按请求字段统计 |
| total_count_exact | boolean | 否 | 计数是否精确 |
| aggregations_exact | boolean | 否 | 统计是否精确 |

## SemanticSearchResult [#semanticsearchresult]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| hits | SemanticHit[] | 是 | 检索命中 |
| embedding_producer | string | 是 | 语义理解生成者 |
| not_ready_excluded | number | 是 | 因未就绪而排除的素材数 |

## SearchAsset [#searchasset]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| 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 | 否 | 预览海报和故事板 |

## SemanticHit [#semantichit]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| asset | Asset | 是 | 命中的素材 |
| score | number | 是 | 相关度分数 |
| semantic_score | number / null | 否 | — |
| matches | SemanticMatch[] | 是 | 匹配内容与片段时间 |

## SemanticMatch [#semanticmatch]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| kind | UnderstandingKind / "metadata" / "image" | 是 | 理解或处理种类；列出理解结果时按此筛选 |
| understanding_id | UnderstandingId / null | 是 | 对应的理解记录；元数据命中为空 |
| segment | Segment / null | 是 | 起止毫秒；整份素材为 null |
| snippet | string | 是 | 命中文字片段 |