Praxis文档
控制台
Cloudinary

检索

端点与支持范围。

指南 →

表达式检索仅支持以下子集。不支持的语法或字段返回 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 / ab不支持，返回 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. 指南 →

基础地址与鉴权

以图搜图

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

参数位置类型说明
library_idpathstring库 ID
image_asset_idquerystring本库素材 ID
image_urlquerystring仅接受本库交付 URL，不支持抓取外部 URL
textquerystring自然语言查询，使用语义检索
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
filterquerystring表达式筛选条件

返回: 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

Successful response.

application/json

名称类型说明
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject

以图搜图

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

参数位置类型说明
library_idpathstring库 ID

请求体

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

返回: 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

Successful response.

application/json

名称类型说明
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject

表达式检索

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

参数位置类型说明
library_idpathstring库 ID
expressionquerystring结构化查询表达式；空表达式返回全部素材
sort_byquerystring排序字段与方向
max_resultsqueryinteger最多 500；检索默认 100，Admin 默认 10
next_cursorquerystring下一页游标；没有时为 null 或省略
with_fieldquerystring[]额外返回 tags 或 context
aggregatequerystring[]统计字段

返回: CompatExpressionSearchResult.

响应

HTTP 200

Successful response.

application/json

名称类型说明
total_countnumber
timenumber
next_cursorstring
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject
aggregationsobject
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

{
  "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
    }
  ]
}

表达式检索

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

参数位置类型说明
library_idpathstring库 ID

请求体

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

返回: CompatExpressionSearchResult.

响应

HTTP 200

Successful response.

application/json

名称类型说明
total_countnumber
timenumber
next_cursorstring
resourcesarray<object>
resources[].asset_idstring
resources[].public_idstring
resources[].display_namestring
resources[].asset_folderstring
resources[].resource_typestring
resources[].typestring
resources[].formatstring
resources[].versionnumber
resources[].version_idstring
resources[].bytesnumber
resources[].etagstring
resources[].widthnumber
resources[].heightnumber
resources[].durationnumber
resources[].pagesnumber
resources[].is_audioboolean
resources[].original_filenamestring
resources[].tagsarray<string>
resources[].contextobject
resources[].created_atstring
resources[].urlstring
resources[].secure_urlstring
resources[].placeholderboolean
resources[].existingboolean
resources[].processingobject
aggregationsobject
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

{
  "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

字段类型必填说明
resourcesCloudinaryResource[]是本页素材

CompatExpressionSearchResult

字段类型必填说明
total_countnumber是匹配总数
timenumber是检索耗时，整数毫秒，由服务端测得
next_cursorstring否下一页游标；没有时为 null 或省略
resourcesSearchResource[]是本页素材
aggregationsobject否按请求字段统计

SearchResource

字段类型必填说明
asset_idAssetId是素材 ID
public_idstring是交付地址中的素材名称，可带路径
display_namestring是显示名称
asset_folderstring是组织文件夹；不改变 public_id。按它列出时只匹配这一层、不含子文件夹；空字符串表示根
resource_typeResourceType是image、video（含音频）或 raw；auto 只用于上传，列表传 auto 或其他值返回 400
typeDeliveryType是资源或事件类型
formatstring是文件格式
versionnumber是交付版本号
version_idstring是版本标识
bytesnumber是文件字节数
etagstring是文件校验标识
widthnumber否宽度像素
heightnumber否高度像素
durationnumber否时长秒数
pagesnumber否文档页数
is_audioboolean否是否为音频
original_filenamestring否原文件名称
tagsstring[]否素材标签。上传可传逗号分隔字符串（每项去首尾空白、丢弃空项）、数组或重复的 tags 字段；PATCH 只接受数组并整体替换
contextobject否自定义文字键值；PATCH 整体替换，传 {} 清空
created_atIsoTimestamp是创建时间
urlstring是原文件地址
secure_urlstring是HTTPS 交付地址
placeholderfalse是固定为 false
existingboolean否未覆盖时是否返回已有素材
processingProcessing否整体与各项理解状态

资源管理

端点与支持范围。

交付与变换

交付地址和允许的变换。

导出
本页 Markdown本节 Markdown整本 PDF

本页内容

以图搜图响应HTTP 200以图搜图请求体响应HTTP 200表达式检索响应HTTP 200表达式检索请求体响应HTTP 200VisualResourcesCompatExpressionSearchResultSearchResource