# 检索 (/docs/api/compatible/cloudinary/search)



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

表达式检索仅支持以下子集。不支持的语法或字段返回 HTTP 400 INVALID\_EXPRESSION；兼容错误体只包含消息。默认省略 tags 与 context；需要时用 with\_field 请求。

| 语法 | 含义 |
| --- | --- |
| AND / OR / NOT / - / ( ) | 布尔组合；相邻条件默认 AND |
| field:value / field=value | 字段匹配 |
| bytes > 1000 / width >= 160 | 数值比较；也支持 height、duration |
| created_at >= 2026-01-01 / uploaded_at > 7d | 日期或相对时间，支持 d/w/m/y |
| tags:docs / context.alt:"sample image" | 标签和自定义文字 |
| public_id:docs* | 仅末尾通配符 |
| "sample image" | 短语 |
| sunset | 裸词：在 public_id、display_name、tags、context 以及理解得到的描述、图片文字、转写中做全文匹配，不区分大小写 |
| ~ / ^ / [a TO z] / *prefix / a*b | 不支持，返回 400 |

字段名不区分大小写（RESOURCE\_TYPE:image 等同 resource\_type:image）；resource\_type、type、format 的值不区分大小写；tags、context 等其他字段的值区分大小写。空表达式返回全部素材；无法解析的表达式返回 400 INVALID\_EXPRESSION。

查询字段: `asset_id, resource_type, type, format, public_id, asset_folder, display_name, tags, bytes, width, height, duration, created_at, uploaded_at, context.<key>`.

排序字段: `created_at, public_id, display_name, bytes, uploaded_at`.

统计字段: `resource_type, format, asset_folder, processing_state`.
[指南 →](/docs/cloud/services/media/quickstart)

[基础地址与鉴权](/docs/api/compatible/cloudinary)

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

`GET /cloudinary/v1_1/{library_id}/resources/visual_search`

| 参数 | 位置 | 类型 | 说明 |
| --- | --- | --- | --- |
| library_id | path | string | 库 ID |
| image_asset_id | query | string | 本库素材 ID |
| image_url | query | string | 仅接受本库交付 URL，不支持抓取外部 URL |
| text | query | string | 自然语言查询，使用语义检索 |
| max_results | query | integer | 最多 500；检索默认 100，Admin 默认 10 |
| filter | query | string | 表达式筛选条件 |

返回: `VisualResources`.

库的 `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。

`image_asset_id`、`image_file`（multipart）、`image_url`、`text` 必须且只能传一个。text 使用纯语义检索；返回 `{ "resources": [...] }`。image\_url 只接受本库交付 URL，不抓取外部 URL；外部 URL 返回 400「不支持抓取外部 URL」。

### 响应 [#响应]

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array&lt;object&gt; |  |
| resources[].asset_id | string |  |
| resources[].public_id | string |  |
| resources[].display_name | string |  |
| resources[].asset_folder | string |  |
| resources[].resource_type | string |  |
| resources[].type | string |  |
| resources[].format | string |  |
| resources[].version | number |  |
| resources[].version_id | string |  |
| resources[].bytes | number |  |
| resources[].etag | string |  |
| resources[].width | number |  |
| resources[].height | number |  |
| resources[].duration | number |  |
| resources[].pages | number |  |
| resources[].is_audio | boolean |  |
| resources[].original_filename | string |  |
| resources[].tags | array&lt;string&gt; |  |
| resources[].context | object |  |
| resources[].created_at | string |  |
| resources[].url | string |  |
| resources[].secure_url | string |  |
| resources[].placeholder | boolean |  |
| resources[].existing | boolean |  |
| resources[].processing | object |  |

## 以图搜图 [#以图搜图-1]

`POST /cloudinary/v1_1/{library_id}/resources/visual_search`

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

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

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| image_asset_id | string | 否 | 本库素材 ID |
| image_url | string | 否 | 仅接受本库交付 URL，不支持抓取外部 URL |
| image_file | string | 否 | JPEG、PNG、WebP 或 GIF 文件，最大 10 MiB |
| text | string | 否 | 自然语言查询，使用语义检索 |
| max_results | integer | 否 | 最多 500；检索默认 100，Admin 默认 10 |
| filter | string | 否 | 表达式筛选条件 |

返回: `VisualResources`.

库的 `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。

`image_asset_id`、`image_file`（multipart）、`image_url`、`text` 必须且只能传一个。text 使用纯语义检索；返回 `{ "resources": [...] }`。image\_url 只接受本库交付 URL，不抓取外部 URL；外部 URL 返回 400「不支持抓取外部 URL」。

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| resources | array&lt;object&gt; |  |
| resources[].asset_id | string |  |
| resources[].public_id | string |  |
| resources[].display_name | string |  |
| resources[].asset_folder | string |  |
| resources[].resource_type | string |  |
| resources[].type | string |  |
| resources[].format | string |  |
| resources[].version | number |  |
| resources[].version_id | string |  |
| resources[].bytes | number |  |
| resources[].etag | string |  |
| resources[].width | number |  |
| resources[].height | number |  |
| resources[].duration | number |  |
| resources[].pages | number |  |
| resources[].is_audio | boolean |  |
| resources[].original_filename | string |  |
| resources[].tags | array&lt;string&gt; |  |
| resources[].context | object |  |
| resources[].created_at | string |  |
| resources[].url | string |  |
| resources[].secure_url | string |  |
| resources[].placeholder | boolean |  |
| resources[].existing | boolean |  |
| resources[].processing | object |  |

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

`GET /cloudinary/v1_1/{library_id}/resources/search`

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

返回: `CompatExpressionSearchResult`.

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| total_count | number |  |
| time | number |  |
| next_cursor | string |  |
| resources | array&lt;object&gt; |  |
| resources[].asset_id | string |  |
| resources[].public_id | string |  |
| resources[].display_name | string |  |
| resources[].asset_folder | string |  |
| resources[].resource_type | string |  |
| resources[].type | string |  |
| resources[].format | string |  |
| resources[].version | number |  |
| resources[].version_id | string |  |
| resources[].bytes | number |  |
| resources[].etag | string |  |
| resources[].width | number |  |
| resources[].height | number |  |
| resources[].duration | number |  |
| resources[].pages | number |  |
| resources[].is_audio | boolean |  |
| resources[].original_filename | string |  |
| resources[].tags | array&lt;string&gt; |  |
| resources[].context | object |  |
| resources[].created_at | string |  |
| resources[].url | string |  |
| resources[].secure_url | string |  |
| resources[].placeholder | boolean |  |
| resources[].existing | boolean |  |
| resources[].processing | object |  |
| aggregations | object |  |

```bash
curl -X GET "https://api.deepraxis.ai/cloudinary/v1_1/${LIBRARY_ID}/resources/search?expression=tags%3Adocs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

HTTP 200

```json
{
  "total_count": 1,
  "time": 0,
  "resources": [
    {
      "asset_id": "9339cdae93804c0c8c65d5189ef1f646",
      "public_id": "docs/pixel",
      "display_name": "Sample image",
      "asset_folder": "examples",
      "resource_type": "image",
      "type": "upload",
      "format": "png",
      "version": 1791538418,
      "version_id": "35848c1529994e338e7aa634a1c13d9c",
      "bytes": 70,
      "etag": "b357a19c87624c7c4d131aeeb4ae677f",
      "width": 1,
      "height": 1,
      "original_filename": "file",
      "created_at": "2026-10-09T09:33:38.899Z",
      "url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
      "secure_url": "https://media-develop.praxisusercontent.com/lib_77374d4ee73b4ae79c4aa430f3ba3885/image/upload/v1791538418/docs/pixel.png",
      "placeholder": false
    }
  ]
}
```

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

`POST /cloudinary/v1_1/{library_id}/resources/search`

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

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

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

返回: `CompatExpressionSearchResult`.

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

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

Successful response.

**application/json**

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| total_count | number |  |
| time | number |  |
| next_cursor | string |  |
| resources | array&lt;object&gt; |  |
| resources[].asset_id | string |  |
| resources[].public_id | string |  |
| resources[].display_name | string |  |
| resources[].asset_folder | string |  |
| resources[].resource_type | string |  |
| resources[].type | string |  |
| resources[].format | string |  |
| resources[].version | number |  |
| resources[].version_id | string |  |
| resources[].bytes | number |  |
| resources[].etag | string |  |
| resources[].width | number |  |
| resources[].height | number |  |
| resources[].duration | number |  |
| resources[].pages | number |  |
| resources[].is_audio | boolean |  |
| resources[].original_filename | string |  |
| resources[].tags | array&lt;string&gt; |  |
| resources[].context | object |  |
| resources[].created_at | string |  |
| resources[].url | string |  |
| resources[].secure_url | string |  |
| resources[].placeholder | boolean |  |
| resources[].existing | boolean |  |
| resources[].processing | object |  |
| aggregations | object |  |

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

HTTP 200

```json
{
  "total_count": 2,
  "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": "running",
          "visual": "failed",
          "tagging": "failed"
        },
        "updated_at": "2026-10-11T15:50:21.512Z"
      },
      "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
    },
    {
      "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
    }
  ]
}
```

## VisualResources [#visualresources]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| resources | CloudinaryResource[] | 是 | 本页素材 |

## CompatExpressionSearchResult [#compatexpressionsearchresult]

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

## SearchResource [#searchresource]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| 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 整体替换，传 &#123;&#125; 清空 |
| created_at | IsoTimestamp | 是 | 创建时间 |
| url | string | 是 | 原文件地址 |
| secure_url | string | 是 | HTTPS 交付地址 |
| placeholder | false | 是 | 固定为 false |
| existing | boolean | 否 | 未覆盖时是否返回已有素材 |
| processing | Processing | 否 | 整体与各项理解状态 |