Tag Image In Stream - Tag Image In Stream

Service:

Azure AI Services

API Version:

3.2

This operation generates a list of words, or tags, that are relevant to the content of the supplied image. The Computer Vision API can return tags based on objects, living beings, scenery or actions found in images. Unlike categories, tags are not organized according to a hierarchical classification system, but correspond to image content. Tags may contain hints to avoid ambiguity or provide context, for example the tag "ascomycete" may be accompanied by the hint "fungus". Two input methods are supported -- (1) Uploading an image or (2) specifying an image URL. A successful response will be returned in JSON. If the request failed, the response will contain an error code and a message to help understand what went wrong.

POST {Endpoint}/vision/v3.2/tag

With optional parameters:

POST {Endpoint}/vision/v3.2/tag?overload=stream&language={language}&model-version={model-version}

URI Parameters

Name	In	Required	Type	Description
Endpoint	path	True	string	Supported Cognitive Services endpoints.
language	query		string	The desired language for output generation. If this parameter is not specified, the default value is "en". See https://aka.ms/cv-languages for list of supported languages.
model-version	query		string pattern: ^(latest|\d{4}-\d{2}-\d{2})(-preview)?$	Optional parameter to specify the version of the AI model. Accepted values are: "latest", "2021-04-01", "2021-05-01". Defaults to "latest".

Request Header

Media Types: "application/octet-stream", "multipart/form-data"

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string

Request Body

Media Types: "application/octet-stream", "multipart/form-data"

Name	Type	Description
Image	object (file)	An image stream.

Responses

Name	Type	Description
200 OK	TagResult	Image tags object.
Other Status Codes	ComputerVisionErrorResponse	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Successful TagImage request

Sample request

HTTP

POST https://westus.api.cognitive.microsoft.com/vision/v3.2/tag?overload=stream


"{binary}"

Sample response

Status code:

200

{
  "tags": [
    {
      "name": "grass",
      "confidence": 0.9999997615814209
    },
    {
      "name": "outdoor",
      "confidence": 0.9999706745147705
    },
    {
      "name": "sky",
      "confidence": 0.9992897510528564
    },
    {
      "name": "building",
      "confidence": 0.9964632391929626
    },
    {
      "name": "house",
      "confidence": 0.9927980303764343
    },
    {
      "name": "lawn",
      "confidence": 0.8226802945137024
    },
    {
      "name": "green",
      "confidence": 0.6412225365638733
    },
    {
      "name": "residential",
      "confidence": 0.31403225660324097
    }
  ],
  "requestId": "1ad0e45e-b7b4-4be3-8042-53be96103337",
  "metadata": {
    "width": 400,
    "height": 400,
    "format": "Jpeg"
  },
  "modelVersion": "2021-04-01"
}

Definitions

Name	Description
ComputerVisionError	The API request error.
ComputerVisionErrorCodes	The error code.
ComputerVisionErrorResponse	The API error response.
ComputerVisionInnerError	Details about the API request error.
ComputerVisionInnerErrorCodeValue	The error code.
ImageMetadata	Image metadata.
ImageTag	An entity observation in the image, along with the confidence score.
TagResult	The results of a image tag operation, including any tags and image metadata.

ComputerVisionError

Object

The API request error.

Name	Type	Description
code	ComputerVisionErrorCodes	The error code.
innererror	ComputerVisionInnerError	Inner error contains more specific information.
message	string	A message explaining the error reported by the service.

ComputerVisionErrorCodes

Enumeration

The error code.

Value	Description
InvalidRequest
InvalidArgument
InternalServerError
ServiceUnavailable

ComputerVisionErrorResponse

Object

The API error response.

Name	Type	Description
error	ComputerVisionError	Error contents.

ComputerVisionInnerError

Object

Details about the API request error.

Name	Type	Description
code	ComputerVisionInnerErrorCodeValue	The error code.
message	string	Error message.

ComputerVisionInnerErrorCodeValue

Enumeration

The error code.

Value	Description
InvalidImageFormat
UnsupportedMediaType
InvalidImageUrl
NotSupportedFeature
NotSupportedImage
Timeout
InternalServerError
InvalidImageSize
BadArgument
DetectFaceError
NotSupportedLanguage
InvalidThumbnailSize
InvalidDetails
InvalidModel
CancelledRequest
NotSupportedVisualFeature
FailedToProcess
Unspecified
StorageException

ImageMetadata

Object

Image metadata.

Name	Type	Description
format	string	Image format.
height	integer (int32)	Image height, in pixels.
width	integer (int32)	Image width, in pixels.

ImageTag

Object

An entity observation in the image, along with the confidence score.

Name	Type	Description
confidence	number (double)	The level of confidence that the entity was observed.
hint	string	Optional hint/details for this tag.
name	string	Name of the entity.

TagResult

Object

The results of a image tag operation, including any tags and image metadata.

Name	Type	Description
metadata	ImageMetadata	Image metadata.
modelVersion	string pattern: ^(latest|\d{4}-\d{2}-\d{2})(-preview)?$	Version of the AI model.
requestId	string	Id of the REST API request.
tags	ImageTag[]	A list of tags with confidence level.