端點：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 |
Yes |
字串 |
- |
一個搜尋查詢字串。 長度上限為 1000 個字元。 |
maxResults |
No |
整數 |
30 |
要傳回的結果數目上限。 預設值是30，最高值是30。 |
language |
No |
字串 |
「en」 |
搜尋結果中介面語言的兩字母 ISO 639-1 語言代碼。 完整列表請參閱 支援語言 。 |
region |
No |
字串 |
"US" |
一個兩字母的國家/地區代碼，表示結果應該來自哪裡（例如「US」、「JP」、「CN」）。 完整列表請參閱 支援區域 。 |
aspectRatio |
No |
字串（列舉） |
- |
依照長寬比過濾圖片。 數值：「正方形」（約1：1）、「寬」（寬 > 度高度）、「高」（高度 > 寬度）。 未設定時，則不會被過濾。 |
color |
No |
字串（列舉） |
- |
依圖片顏色篩選圖片。 數值：「colorOnly」（僅回傳彩色影像）、「monochrome」（僅回傳黑白影像）。 未設定時，則不會被過濾。 |
safeSearch |
No |
字串（列舉） |
「嚴格」 |
安全搜尋篩選的層級。 價值觀：「關」、「嚴格」。 預設是「嚴格」。 |
imageSize |
No |
字串（列舉） |
- |
依尺寸分類篩選圖片。 數值：「小」（<200x200px）、「中」（寬或高 200-500px）、「大」（寬或高 >=500px）、「超大」（>1024x768px）。 也可以使用像素限制（maxHeight、minHeight、maxWidth、minWidth）來自訂邊界;當像素限制發生衝突時，會優先於 imageSize。 未設定時，則不會被過濾。 |
watermarkFree |
No |
boolean |
假的 |
排除帶有浮水印的圖片。 預設值為 false。 |
maxHeight |
No |
整數 |
- |
最大影像高度（像素單位）。 搭配 imageSize 進行自訂邊界。 |
minHeight |
No |
整數 |
- |
最小影像高度（像素單位）。 |
maxWidth |
No |
整數 |
- |
最大影像寬度（像素）。 |
minWidth |
No |
整數 |
- |
最小影像寬度（像素單位）。 |
| Field |
類型 |
Description |
| 主持人 |
字串 |
Microsoft AI API 主機： api.microsoft.ai |
| x-apikey 或 授權 |
字串 |
你的 API 金鑰或 Entra ID 存取權杖用於認證。 |
| 內容類型 |
字串 |
請求實體的 MIME 類型。 請使用 application/json。 |
回應
圖片回應
| Field |
類型 |
Description |
imageResults |
ImageResult 陣列 |
圖片結果列表。 |
instrumentationClickBase |
字串 |
點擊ping請求的基礎網址。 從 instrumentationSuffix 結果項目附加一個值，形成完整的 ping URL。 僅用於帶有 EnableInstrumentationPing 設定檔標誌的應用程式。 注意：使用者點擊也可透過網址重定向來記錄。 啟用重定向時，無需操作記錄使用者點擊，且 instrumentationClickBase 回應中不會包含。 請參閱 儀器安裝指南 以了解設定說明。 |
instrumentationCitationBase |
字串 |
LLM 日誌 ping 請求的基礎網址。 附加一個 DATA payload 以形成完整的 ping URL。 僅用於帶有 EnableInstrumentationPing 設定檔標誌的應用程式。 |
traceId |
字串 |
追蹤識別碼用於除錯與追蹤。 |
影像結果
| Field |
類型 |
Description |
title |
字串 |
圖片標題。 |
url |
字串 |
圖片的來源網址。 對於啟用 URL 重定向的中國用戶，此欄位會包含與 clickUrl相同的重定向 URL。 |
domain |
字串 |
結果的目的地主機。 僅針對啟用 URL 重定向的中國用戶退回。 |
hostPageUrl |
字串 |
該圖片所載網頁的網址。 |
caption |
字串 |
生成圖片描述。 |
width |
整數 |
影像的寬度，以像素為單位。 |
height |
整數 |
圖片高度，以像素為單位。 |
thumbnailUrl |
字串 |
圖片的縮圖來源網址。 |
lastUpdatedAt |
字串 |
圖片的最後更新日期依照ISO8601格式。 |
isAdult |
boolean |
標示內容是否為成人內容。 |
clickUrl |
字串 |
透過 Bing 將點擊的代理網址重新導轉。 只有在啟用點擊重定向時才會出現。 |
instrumentationSuffix |
字串 |
附加於此結果項目的儀器 ping URL 基底後綴。 用作儀器 ping URL 與重定向的 clickUrl K 值。 啟用儀器 ping 時仍會顯示。 |
錯誤代碼
| 狀態代碼 |
錯誤類別 |
Description |
常見的原因 |
| 200 |
Success |
請求成功。 |
- |
| 400 |
錯誤的請求 |
請求參數無效。 |
缺少必填欄位、參數值無效、JSON 格式錯誤 |
| 401 |
Unauthorized |
驗證失敗或缺失。 |
API 金鑰無效，缺少 x-apikey 標頭 |
| 403 |
禁止 |
有效的憑證，但權限不足。 |
API 金鑰缺乏所需權限 |
| 410 |
消失了 |
需要 HTTPS 認證。 |
請求是透過 HTTP 而非 HTTPS 進行的 |
| 415 |
不支援媒體類型 |
內容類型不支援。 |
缺少或錯誤的內容類型標頭 |
| 429 |
過多要求 |
速率超過上限。 |
時間窗口內請求太多 |
| 500 |
內部伺服器錯誤 |
未預期的伺服器錯誤。 |
臨時伺服器問題 |
| 503 |
服務不可用 |
服務暫時無法使用。 |
維護或暫時停電 |
| 504 |
閘道逾時 |
要求已逾時。 |
上游服務逾時 |
如需詳細的錯誤處理指引，請參見 錯誤處理。
另見：網路搜尋 | 影片 搜尋 | 瀏覽 | 新聞 搜尋 MCP |