Image Search REST API reference

Endpoint: POST https://api.microsoft.ai/v3/search/images

Sample Request:

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

Parameter	Required	Type	Default	Description
query	Yes	string	-	A search query string. Maximum length is 1000 characters.
maxResults	No	integer	30	Max number of results to return. Default is 30 and maximum value is 30.
language	No	string	"en"	A 2-letter ISO 639-1 language code for interface language in the search results. See Supported Languages for the full list.
region	No	string	"US"	A 2-letter country/region code for where the results should come from (e.g. "US", "JP", "CN"). See Supported Regions for the full list.
aspectRatio	No	string(enum)	-	Filter images by aspect ratio. Values: "square" (roughly 1:1), "wide" (width > height), "tall" (height > width). When not set, no filtering is applied.
color	No	string(enum)	-	Filter images by image color. Values: "colorOnly" (only return color images), "monochrome" (only return black and white images). When not set, no filtering is applied.
safeSearch	No	string(enum)	"strict"	Level of safe search filtering. Values: "off", "strict". Default is "strict".
imageSize	No	string(enum)	-	Filter images by size category. Values: "small" (<200x200px), "medium" (width or height 200-500px), "large" (width or height >=500px), "extraLarge" (>1024x768px). Can also use pixel constraints (maxHeight, minHeight, maxWidth, minWidth) for custom bounds; pixel constraints take precedence over imageSize when they conflict. When not set, no filtering is applied.
watermarkFree	No	boolean	false	Exclude images with watermark. Default is false.
maxHeight	No	integer	-	Maximum image height in pixels. Used with imageSize for custom bounds.
minHeight	No	integer	-	Minimum image height in pixels.
maxWidth	No	integer	-	Maximum image width in pixels.
minWidth	No	integer	-	Minimum image width in pixels.

Request Headers

Field	Type	Description
host	string	Host for Microsoft AI APIs: api.microsoft.ai.
x-apikey or Authorization	string	Your API key or Entra ID access token for authentication.
content-type	string	MIME type of the request body. Use application/json.

Response

ImagesResponse

Field	Type	Description
imageResults	array of ImageResult	List of image results.
instrumentationClickBase	string	Base URL for click ping requests. Append an instrumentationSuffix value from a result item to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. Note: User clicks can also be logged using URL redirection. When redirection is enabled, no action is required to log User clicks, and instrumentationClickBase will not be included in the response. See the Instrumentation guide for setup instructions.
instrumentationCitationBase	string	Base URL for LLM log ping requests. Append a DATA payload to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag.
traceId	string	Trace ID for debugging and tracking.

ImageResult

Field	Type	Description
title	string	The title of the image.
url	string	The source URL of the image. For China users with URL redirection enabled, this field instead contains the same redirect URL as clickUrl.
domain	string	The destination host for the result. Returned only for China users with URL redirection enabled.
hostPageUrl	string	The URL of the webpage that hosts the image.
caption	string	Generated description of the image.
width	integer	The width of the image, in pixels.
height	integer	The height of the image, in pixels.
thumbnailUrl	string	The thumbnail source URL of the image.
lastUpdatedAt	string	The last updated date of the image, follows ISO8601 format.
isAdult	boolean	Indicates whether the content is adult content.
clickUrl	string	Redirect URL that proxies the click through Bing. Only present when click redirect is enabled.
instrumentationSuffix	string	Suffix to append to the instrumentation ping URL base for this result item. Used as the K value for both the instrumentation ping URL and the clickUrl redirect. Present when instrumentation ping is enabled.

Error Codes

Status Code	Error Category	Description	Common Causes
200	Success	The request succeeded.	-
400	Bad Request	Invalid request parameters.	Missing required fields, invalid parameter values, malformed JSON
401	Unauthorized	Authentication failed or missing.	Invalid API key, missing x-apikey header
403	Forbidden	Valid credentials but insufficient permissions.	API key lacks required permissions
410	Gone	HTTPS required.	Request made over HTTP instead of HTTPS
415	Unsupported Media Type	Content type not supported.	Missing or incorrect content-type header
429	Too Many Requests	Rate limit exceeded.	Too many requests in time window
500	Internal Server Error	Unexpected server error.	Temporary server issue
503	Service Unavailable	Service temporarily unavailable.	Maintenance or temporary outage
504	Gateway Timeout	Request timed out.	Upstream service timeout

For detailed error handling guidance, see Error Handling.

---

See also: Web Search | Videos Search | Browse | News Search | MCP