终结点：POST https://api.microsoft.ai/v3/search/images
示例请求：
curl -X POST "https://api.microsoft.ai/v3/search/images" \
-H "host: api.microsoft.ai" \
-H "x-apikey: <Your key>" \
-H 'content-type: application/json' \
-d '{
"query": "cats",
"maxResults": 2,
"language": "en",
"region": "US"
}'
Parameters
| 参数 |
Required |
类型 |
Default |
Description |
query |
是 |
字符串 |
- |
搜索查询字符串。 最大长度为 1000 个字符。 |
maxResults |
否 |
整数 |
30 |
要返回的最大结果数。 默认值为 30，最大值为 30。 |
language |
否 |
字符串 |
“en” |
搜索结果中接口语言的 2 字母 ISO 639-1 语言代码。 有关完整列表，请参阅 “支持的语言 ”。 |
region |
否 |
字符串 |
"US" |
结果应来自（例如“US”、“JP”、“CN”）的 2 个字母国家/地区代码。 有关完整列表，请参阅 “支持的区域 ”。 |
aspectRatio |
否 |
string（枚举） |
- |
按纵横比筛选图像。 值：“平方”（大约 1：1）、“宽”（宽度 > 高度）、“高”（高度 > 宽度）。 如果未设置，则不会应用筛选。 |
color |
否 |
string（枚举） |
- |
按图像颜色筛选图像。 值：“colorOnly”（仅返回颜色图像）、“单色”（仅返回黑白图像）。 如果未设置，则不会应用筛选。 |
safeSearch |
否 |
string（枚举） |
“strict” |
安全搜索筛选级别。 值：“off”、“strict”。 默认值为“strict”。 |
imageSize |
否 |
string（枚举） |
- |
按大小类别筛选图像。 值：“small”（<200x200px）、“medium”（宽度或高度 200-500px）、“large”（宽度或高度 >=500px）、“extraLarge”（>1024x768px）。 还可以对自定义边界使用像素约束（maxHeight、minHeight、maxWidth、minWidth）：像素约束在冲突时优先于 imageSize。 如果未设置，则不会应用筛选。 |
watermarkFree |
否 |
boolean |
false |
排除带有水印的图像。 默认值为 false。 |
maxHeight |
否 |
整数 |
- |
最大图像高度（以像素为单位）。 用于自定义边界的 imageSize。 |
minHeight |
否 |
整数 |
- |
最小图像高度（以像素为单位）。 |
maxWidth |
否 |
整数 |
- |
最大图像宽度（以像素为单位）。 |
minWidth |
否 |
整数 |
- |
最小图像宽度（以像素为单位）。 |
| 领域 |
类型 |
Description |
| 主持人 |
字符串 |
适用于 Microsoft AI API 的主机：api.microsoft.ai. |
| x-apikey 或 授权 |
字符串 |
API 密钥或Entra ID访问令牌进行身份验证。 |
| Content-Type |
字符串 |
请求正文的 MIME 类型。 使用 application/json。 |
响应
ImagesResponse
| 领域 |
类型 |
Description |
imageResults |
ImageResult 数组 |
图像结果列表。 |
instrumentationClickBase |
字符串 |
单击 ping 请求的基 URL。 在结果项中追加一个 instrumentationSuffix 值，以形成完整的 ping URL。 仅适用于具有 EnableInstrumentationPing 配置文件标志的应用程序。 注意：还可以使用 URL 重定向记录用户单击。 启用重定向后，无需执行任何操作即可记录用户单击，并且 instrumentationClickBase 不会包含在响应中。 有关设置说明，请参阅 检测指南 。 |
instrumentationCitationBase |
字符串 |
LLM 日志 ping 请求的基 URL。 追加数据有效负载以形成完整的 ping URL。 仅适用于具有 EnableInstrumentationPing 配置文件标志的应用程序。 |
traceId |
字符串 |
用于调试和跟踪的跟踪 ID。 |
ImageResult
| 领域 |
类型 |
Description |
title |
字符串 |
图像的标题。 |
url |
字符串 |
图像的源 URL。 对于启用了 URL 重定向的中国用户，此字段包含的重定向 URL 与 clickUrl. |
domain |
字符串 |
结果的目标主机。 仅针对启用了 URL 重定向的中国用户返回。 |
hostPageUrl |
字符串 |
承载图像的网页的 URL。 |
caption |
字符串 |
生成的映像说明。 |
width |
整数 |
图像的宽度（以像素为单位）。 |
height |
整数 |
图像的高度（以像素为单位）。 |
thumbnailUrl |
字符串 |
图像的缩略图源 URL。 |
lastUpdatedAt |
字符串 |
映像的上次更新日期遵循ISO8601格式。 |
isAdult |
boolean |
指示内容是否为成人内容。 |
clickUrl |
字符串 |
通过必应代理单击的重定向 URL。 仅当启用单击重定向时才会显示。 |
instrumentationSuffix |
字符串 |
要追加到此结果项的检测 ping URL 基的后缀。 用作检测 ping URL 和重定向的 clickUrl K 值。 启用检测 ping 时存在。 |
错误代码
| 状态代码 |
错误类别 |
Description |
常见原因 |
| 200 |
成功 |
请求成功。 |
- |
| 400 |
错误的请求 |
无效的请求参数。 |
缺少必填字段、无效参数值、格式不正确的 JSON |
| 401 |
Unauthorized |
身份验证失败或缺失。 |
API 密钥无效，缺少 x-apikey 标头 |
| 403 |
禁止 |
有效凭据但权限不足。 |
API 密钥缺少所需的权限 |
| 410 |
不存在 (Gone) |
需要 HTTPS。 |
通过 HTTP 而不是 HTTPS 发出的请求 |
| 415 |
不支持的媒体类型 |
不支持内容类型。 |
缺少或不正确的内容类型标头 |
| 429 |
请求过多 |
超出速率限制。 |
时间范围内请求过多 |
| 500 |
内部服务器错误 |
意外的服务器错误。 |
临时服务器问题 |
| 503 |
服务不可用 |
服务暂时不可用。 |
维护或临时中断 |
| 504 |
网关超时 |
请求已超时。 |
上游服务超时 |
有关详细的错误处理指南，请参阅 错误处理。
另请参阅：Web 搜索 | 视频搜索 | 浏览 | 新闻搜索 | MCP