使用 Bing 影像搜尋 API 從 Web 取得影像Get images from the web with the Bing Image Search API

當您使用 Bing 影像搜尋 REST API 時,您可以藉由傳送下列 GET 要求,從 Web 中取得與使用者搜尋字詞相關的影像:When you use the Bing Image Search REST API, you can get images from the web that are related to your search term by sending the following GET request:

GET https://api.cognitive.microsoft.com/bing/v7.0/images/search?q=sailing+dinghies&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
X-MSEdge-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

使用q查詢參數,您的 url 編碼的搜尋字詞。Use the q query parameter for your url-encoded search term. 例如,如果您輸入 sailing dinghies,請將 q 設定為 sailing+dinghiessailing%20dinghiesFor example, if you enter sailing dinghies, set q to sailing+dinghies or sailing%20dinghies.

重要

  • 所有要求都必須是從伺服器進行,不能從用戶端進行。All requests must be made from a server, and not from a client.
  • 如果這是您第一次呼叫任何 Bing 搜尋 API,請勿包含用戶端識別碼標頭。If it's your first time calling any of the Bing search APIs, don't include the client ID header. 如果您先前已呼叫 Bing API,並且傳回了使用者和裝置組合的用戶端識別碼,才需包含用戶端識別碼。Only include the client ID if you've previously called a Bing API that returned a client ID for the user and device combination.

從特定 Web 網域中取得影像Get images from a specific web domain

若要從特定網域取得影像,請使用 site: 查詢運算子。To get images from a specific domain, use the site: query operator.

GET https://api.cognitive.microsoft.com/bing/v7.0/images/search?q=sailing+dinghies+site:contososailing.com&mkt=en-us HTTP/1.1

注意

不論是否有 safeSearch 設定,使用 site: 運算子的查詢回應都可能包含成人內容。Responses to queries using the site: operator might include adult content regardless of the safeSearch setting. 請只在您知曉網域上的內容時,才使用 site:Only use site: if you're aware of the content on the domain.

篩選影像Filter images

根據預設,影像搜尋 API 會傳回與查詢相關的所有影像。By default, the Image Search API returns all images that are relevant to the query. 如果您想要篩選 Bing 所傳回的影像 (例如,只傳回具有透明背景或特定大小的影像),請使用下列查詢參數:If you want to filter the images that Bing returns (for example, to return only images with a transparent background or specific size), use the following query parameters:

  • aspect:依照外觀比例篩選影像 (例如,標準或寬螢幕影像)。aspect—Filter images by aspect ratio (for example, standard or wide screen images).
  • color:依照主色或黑白篩選影像。color—Filter images by dominant color or black and white.
  • freshness:依照存在時間篩選影像 (例如,Bing 在過去一週中探索的影像)。freshness—Filter images by age (for example, images discovered by Bing in the past week).
  • heightwidth:依照寬度和高度篩選影像。height, width—Filter images by width and height.
  • imageContent:依照內容篩選影像 (例如只顯示人臉的影像)。imageContent—Filter images by content (for example, images that show only a person's face).
  • imageType:依照類型篩選影像 (例如,美工圖案、動畫 GIF 或透明背景)。imageType—Filter images by type (for example, clip art, animated GIFs, or transparent backgrounds).
  • license:依照與網站相關聯的授權類型篩選影像。license—Filter images by the type of license associated with the site.
  • size:依照大小篩選影像,例如最大 200 x 200 像素的小型影像。size—Filter images by size, such as small images up to 200x200 pixels.

若要從特定網域取得影像,請使用 site: 查詢運算子。To get images from a specific domain, use the site: query operator.

下列範例示範如何從 Bing 在過去一週中探索的 ContosoSailing.com 取得小型影像。The following example shows how to get small images from ContosoSailing.com that Bing discovered in the past week.

GET https://api.cognitive.microsoft.com/bing/v7.0/images/search?q=sailing+dinghies+site:contososailing.com&size=small&freshness=week&mkt=en-us HTTP/1.1  
Ocp-Apim-Subscription-Key: 123456789ABCDE  
X-MSEdge-ClientIP: 999.999.999.999  
X-Search-Location: lat:47.60357;long:-122.3295;re:100  
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>  
Host: api.cognitive.microsoft.com  

Bing 影像搜尋的回應格式Bing Image Search response format

從 Bing 傳回的回應訊息包含影像答案,其中包含認知服務判斷為與查詢相關的影像清單。The response message from Bing contains an Images answer that contains a list of images that Cognitive Services determined to be relevant to the query. 清單中的每個影像物件包含下列影像相關資訊:URL、影像大小、影像維度、影像編碼格式、影像縮圖的 URL 及縮圖的維度。Each Image object in the list includes the following information about the image: the URL, its size, its dimensions, its encoding format, a URL to a thumbnail of the image, and the thumbnail's dimensions.

注意

  • 影像必須以回應中提供的順序來顯示。Images must be displayed in the order provided in the response.
  • 因為 URL 格式和參數有變更恕不另行通知,請使用所有的 Url,做為是。Because URL formats and parameters are subject to change without notice, use all URLs as-is. 您不應該相依於 URL 格式或除了註明的參數。You should not take dependencies on the URL format or parameters except where noted.
{
    "name": "Rich Passage Sailing Dinghy",
    "webSearchUrl": "https:\/\/www.bing.com\/cr?IG=73118C8B4E3...",
    "thumbnailUrl": "https:\/\/tse1.mm.bing.net\/th?id=OIP.GNarK7m...",
    "datePublished": "2011-10-29T11:26:00",
    "contentUrl": "http:\/\/www.bing.com\/cr?IG=73118C8B4E3D4C3...",
    "hostPageUrl": "http:\/\/www.bing.com\/cr?IG=73118C8B4E3D4C3687...",
    "contentSize": "79239 B",
    "encodingFormat": "jpeg",
    "hostPageDisplayUrl": "en.contoso.org\/wiki\/File:Rich_Passage...",
    "width": 526,
    "height": 688,
    "thumbnail": {
        "width": 229,
        "height": 300
    },
    "imageInsightsToken": "ccid_GNarK7ma*mid_CCF85447ADA6...",
    "insightsSourcesSummary": {
        "shoppingSourcesCount": 0,
        "recipeSourcesCount": 0
    },
    "imageId": "CCF85447ADA6FFF9E96E7DF0B796F7A86E34593",
    "accentColor": "376094"
},

當您呼叫 Bing 影像搜尋 API 時,Bing 會傳回結果清單。When you call the Bing Image Search API, Bing returns a list of results. 此清單是查詢相關結果總數的子集。The list is a subset of the total number of results that are relevant to the query. 回應的 totalEstimatedMatches 欄位包含可以檢視的影像數目估計。The response's totalEstimatedMatches field contains an estimate of the number of images that are available to view. 如需有關如何逐頁檢視其餘影像的詳細資訊,請參閱逐頁檢視影像For details about how to page through the rest of the images, see Paging Images.

後續步驟Next steps

如果您從未試用過 Bing 影像搜尋 API,請透過快速入門試用此功能。If you haven't tried the Bing Image Search API before, try a quickstart. 如果您想要尋找更複雜的內容,請嘗試可建立單頁 Web 應用程式的教學課程。If you're looking for something more complex, try the tutorial to create a single-page web app.