Microsoft Azure Imageanalysis:analyze API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Imageanalysis:analyze API
schemes:
- https
tags:
- name: Imageanalysis:analyze
paths:
  /imageanalysis:analyze:
    post:
      operationId: microsoftAzureAnalyzefromimagedata
      description: Performs a single Image Analysis operation
      consumes:
      - application/octet-stream
      parameters:
      - $ref: '#/parameters/Azure.Core.Foundations.ApiVersionParameter'
      - name: features
        in: query
        description: 'A list of visual features to analyze.

          Seven visual features are supported: Caption, DenseCaptions, Read (OCR), Tags, Objects, SmartCrops, and People.

          At least one visual feature must be specified.'
        required: true
        type: array
        items:
          type: string
          enum:
          - tags
          - caption
          - denseCaptions
          - objects
          - read
          - smartCrops
          - people
          x-ms-enum:
            name: VisualFeatures
            modelAsString: true
            values:
            - name: tags
              value: tags
              description: Extract content tags for thousands of recognizable objects, living beings, scenery, and actions that appear in the image.
            - name: caption
              value: caption
              description: Generate a human-readable caption sentence that describes the content of the image.
            - name: denseCaptions
              value: denseCaptions
              description: Generate human-readable caption sentences for up to 10 different regions in the image, including one for the whole image.
            - name: objects
              value: objects
              description: Object detection. This is similar to tags, but focused on detecting physical objects in the image and returning their location.
            - name: read
              value: read
              description: Extract printed or handwritten text from the image. Also known as Optical Character Recognition (OCR).
            - name: smartCrops
              value: smartCrops
              description: Find representative sub-regions of the image for thumbnail generation, at desired aspect ratios, with priority given to detected faces.
            - name: people
              value: people
              description: Detect people in the image and return their location.
        collectionFormat: csv
        minItems: 1
        x-ms-client-name: visualFeatures
      - name: language
        in: query
        description: 'The desired language for result generation (a two-letter language code).

          If this option is not specified, the default value ''en'' is used (English).

          See https://aka.ms/cv-languages for a list of supported languages.'
        required: false
        type: string
        default: en
        minLength: 2
      - name: gender-neutral-caption
        in: query
        description: "Boolean flag for enabling gender-neutral captioning for Caption and Dense Captions features.\nBy default captions may contain gender terms (for example: 'man', 'woman', or 'boy', 'girl'). \nIf you set this to \"true\", those will be replaced with gender-neutral terms (for example: 'person' or 'child')."
        required: false
        type: boolean
        default: false
        x-ms-client-name: genderNeutralCaption
      - name: smartcrops-aspect-ratios
        in: query
        description: 'A list of aspect ratios to use for smart cropping.

          Aspect ratios are calculated by dividing the target crop width in pixels by the height in pixels.

          Supported values are between 0.75 and 1.8 (inclusive).

          If this parameter is not specified, the service will return one crop region with an aspect

          ratio it sees fit between 0.5 and 2.0 (inclusive).'
        required: false
        type: array
        items:
          type: number
          format: float
        collectionFormat: csv
        x-ms-client-name: smartCropsAspectRatios
      - name: model-version
        in: query
        description: 'The version of cloud AI-model used for analysis.

          The format is the following: ''latest'' (default value) or ''YYYY-MM-DD'' or ''YYYY-MM-DD-preview'', where ''YYYY'', ''MM'', ''DD'' are the year, month and day associated with the model.

          This is not commonly set, as the default always gives the latest AI model with recent improvements.

          If however you would like to make sure analysis results do not change over time, set this value to a specific model version.'
        required: false
        type: string
        default: latest
        minLength: 6
        maxLength: 18
        pattern: ^(latest|\d{4}-\d{2}-\d{2})(-preview)?$
        x-ms-client-name: modelVersion
      - name: imageData
        in: body
        description: The image to be analyzed
        required: true
        schema:
          type: string
          format: binary
      responses:
        '200':
          description: The request has succeeded.
          schema:
            $ref: '#/definitions/ImageAnalysisResult'
        default:
          description: An unexpected error response.
          schema:
            $ref: '#/definitions/Azure.Core.Foundations.ErrorResponse'
          headers:
            x-ms-error-code:
              type: string
              description: String error code indicating what went wrong.
      x-ms-examples:
        AnalyzeFromImageData:
          $ref: ./examples/AnalyzeFromImageData_MaximumSet.json
      summary: Microsoft Azure Post Imageanalysis:analyze
      tags:
      - Imageanalysis:analyze
definitions:
  CropRegion:
    type: object
    description: 'A region at the desired aspect ratio that can be used as image thumbnail.

      The region preserves as much content as possible from the analyzed image, with priority given to detected faces.'
    properties:
      aspectRatio:
        type: number
        format: float
        description: 'The aspect ratio of the crop region.

          Aspect ratio is calculated by dividing the width of the region in pixels by its height in pixels.

          The aspect ratio will be in the range 0.75 to 1.8 (inclusive) if provided by the developer during the analyze call.

          Otherwise, it will be in the range 0.5 to 2.0 (inclusive).'
        minimum: 0
      boundingBox:
        $ref: '#/definitions/ImageBoundingBox'
        description: The bounding box of the region.
    required:
    - aspectRatio
    - boundingBox
  TagsResult:
    type: object
    description: 'A list of entities observed in the image. Tags can be physical objects, living being, scenery, or actions

      that appear in the image.'
    properties:
      values:
        type: array
        description: A list of tags.
        minItems: 0
        items:
          $ref: '#/definitions/DetectedTag'
        x-ms-identifiers: []
    required:
    - values
  DetectedTag:
    type: object
    description: 'A content entity observation in the image. A tag can be a physical object, living being, scenery, or action

      that appear in the image.'
    properties:
      confidence:
        type: number
        format: float
        description: 'A score, in the range of 0 to 1 (inclusive), representing the confidence that this entity was observed.

          Higher values indicating higher confidence.'
        minimum: 0
        maximum: 1
      name:
        type: string
        description: Name of the entity.
        minLength: 1
    required:
    - confidence
    - name
  PeopleResult:
    type: object
    description: Represents a list of people detected in an image and their location.
    properties:
      values:
        type: array
        description: A list of people detected in an image and their location.
        minItems: 0
        items:
          $ref: '#/definitions/DetectedPerson'
        x-ms-identifiers: []
    required:
    - values
  Azure.Core.Foundations.Error:
    type: object
    description: The error object.
    properties:
      code:
        type: string
        description: One of a server-defined set of error codes.
      message:
        type: string
        description: A human-readable representation of the error.
      target:
        type: string
        description: The target of the error.
      details:
        type: array
        description: An array of details about specific errors that led to this reported error.
        items:
          $ref: '#/definitions/Azure.Core.Foundations.Error'
        x-ms-identifiers: []
      innererror:
        $ref: '#/definitions/Azure.Core.Foundations.InnerError'
        description: An object containing more specific information than the current object about the error.
    required:
    - code
    - message
  DenseCaption:
    type: object
    description: Represents a generated phrase that describes the content of the whole image or a region in the image
    properties:
      confidence:
        type: number
        format: float
        description: 'A score, in the range of 0 to 1 (inclusive), representing the confidence that this description is accurate.

          Higher values indicating higher confidence.'
        minimum: 0
        maximum: 1
      text:
        type: string
        description: The text of the caption.
        minLength: 1
      boundingBox:
        $ref: '#/definitions/ImageBoundingBox'
        description: The image region of which this caption applies.
    required:
    - confidence
    - text
    - boundingBox
  ImageMetadata:
    type: object
    description: Metadata associated with the analyzed image.
    properties:
      height:
        type: integer
        format: int32
        description: The height of the image in pixels.
        minimum: 1
      width:
        type: integer
        format: int32
        description: The width of the image in pixels.
        minimum: 1
    required:
    - height
    - width
  Azure.Core.Foundations.ErrorResponse:
    type: object
    description: A response containing error details.
    properties:
      error:
        $ref: '#/definitions/Azure.Core.Foundations.Error'
        description: The error object.
    required:
    - error
  ReadResult:
    type: object
    description: The results of a Read (OCR) operation.
    properties:
      blocks:
        type: array
        description: A list of text blocks in the image. At the moment only one block is returned, containing all the text detected in the image.
        minItems: 1
        maxItems: 1
        items:
          $ref: '#/definitions/DetectedTextBlock'
        x-ms-identifiers: []
    required:
    - blocks
  ObjectsResult:
    type: object
    description: Represents a list of physical object detected in an image and their location.
    properties:
      values:
        type: array
        description: A list of physical object detected in an image and their location.
        minItems: 0
        items:
          $ref: '#/definitions/DetectedObject'
        x-ms-identifiers: []
    required:
    - values
  DenseCaptionsResult:
    type: object
    description: 'Represents a list of up to 10 image captions for different regions of the image.

      The first caption always applies to the whole image.'
    properties:
      values:
        type: array
        description: The list of image captions.
        minItems: 1
        items:
          $ref: '#/definitions/DenseCaption'
        x-ms-identifiers: []
    required:
    - values
  DetectedTextWord:
    type: object
    description: "A word object consisting of a contiguous sequence of characters. For non-space delimited languages,\r\nsuch as Chinese, Japanese, and Korean, each character is represented as its own word."
    properties:
      text:
        type: string
        description: Text content of the word.
        minLength: 1
      boundingPolygon:
        type: array
        description: A bounding polygon around the word. At the moment only quadrilaterals are supported (represented by 4 image points).
        minItems: 4
        maxItems: 4
        items:
          $ref: '#/definitions/ImagePoint'
        x-ms-identifiers: []
      confidence:
        type: number
        format: float
        description: The level of confidence that the word was detected. Confidence scores span the range of 0.0 to 1.0 (inclusive), with higher values indicating a higher confidence of detection.
        minimum: 0
        maximum: 1
    required:
    - text
    - boundingPolygon
    - confidence
  DetectedTextBlock:
    type: object
    description: Represents a single block of detected text in the image.
    properties:
      lines:
        type: array
        description: A list of text lines in this block.
        minItems: 1
        items:
          $ref: '#/definitions/DetectedTextLine'
        x-ms-identifiers: []
    required:
    - lines
  ImageAnalysisResult:
    type: object
    description: Represents the outcome of an Image Analysis operation.
    properties:
      captionResult:
        $ref: '#/definitions/CaptionResult'
        description: The generated phrase that describes the content of the analyzed image.
        x-ms-client-name: caption
      denseCaptionsResult:
        $ref: '#/definitions/DenseCaptionsResult'
        description: 'The up to 10 generated phrases, the first describing the content of the whole image,

          and the others describing the content of different regions of the image.'
        x-ms-client-name: denseCaptions
      metadata:
        $ref: '#/definitions/ImageMetadata'
        description: Metadata associated with the analyzed image.
      modelVersion:
        type: string
        description: The cloud AI model used for the analysis
      objectsResult:
        $ref: '#/definitions/ObjectsResult'
        description: A list of detected physical objects in the analyzed image, and their location.
        x-ms-client-name: objects
      peopleResult:
        $ref: '#/definitions/PeopleResult'
        description: A list of detected people in the analyzed image, and their location.
        x-ms-client-name: people
      readResult:
        $ref: '#/definitions/ReadResult'
        description: The extracted printed and hand-written text in the analyze image. Also knows as OCR.
        x-ms-client-name: read
      smartCropsResult:
        $ref: '#/definitions/SmartCropsResult'
        description: 'A list of crop regions at the desired as aspect ratios (if provided) that can be used as image thumbnails.

          These regions preserve as much content as possible from the analyzed image, with priority given to detected faces.'
        x-ms-client-name: smartCrops
      tagsResult:
        $ref: '#/definitions/TagsResult'
        description: A list of content tags in the analyzed image.
        x-ms-client-name: tags
    required:
    - metadata
    - modelVersion
  DetectedObject:
    type: object
    description: Represents a physical object detected in an image.
    properties:
      boundingBox:
        $ref: '#/definitions/ImageBoundingBox'
        description: A rectangular boundary where the object was detected.
      tags:
        type: array
        description: A single-item list containing the object information.
        minItems: 0
        items:
          $ref: '#/definitions/DetectedTag'
        x-ms-identifiers: []
    required:
    - boundingBox
    - tags
  DetectedTextLine:
    type: object
    description: Represents a single line of text in the image.
    properties:
      text:
        type: string
        description: Text content of the detected text line.
        minLength: 1
      boundingPolygon:
        type: array
        description: A bounding polygon around the text line. At the moment only quadrilaterals are supported (represented by 4 image points).
        minItems: 4
        maxItems: 4
        items:
          $ref: '#/definitions/ImagePoint'
        x-ms-identifiers: []
      words:
        type: array
        description: A list of words in this line.
        minItems: 1
        items:
          $ref: '#/definitions/DetectedTextWord'
        x-ms-identifiers: []
    required:
    - text
    - boundingPolygon
    - words
  Azure.Core.Foundations.InnerError:
    type: object
    description: An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
    properties:
      code:
        type: string
        description: One of a server-defined set of error codes.
      innererror:
        $ref: '#/definitions/Azure.Core.Foundations.InnerError'
        description: Inner error.
  ImageBoundingBox:
    type: object
    description: A basic rectangle specifying a sub-region of the image.
    properties:
      x:
        type: integer
        format: int32
        description: X-coordinate of the top left point of the area, in pixels.
        minimum: 0
      y:
        type: integer
        format: int32
        description: Y-coordinate of the top left point of the area, in pixels.
        minimum: 0
      w:
        type: integer
        format: int32
        description: Width of the area, in pixels.
        minimum: 0
        x-ms-client-name: width
      h:
        type: integer
        format: int32
        description: Height of the area, in pixels.
        minimum: 0
        x-ms-client-name: height
    required:
    - x
    - y
    - w
    - h
  SmartCropsResult:
    type: object
    description: 'Smart cropping result. A list of crop regions at the desired as aspect ratios (if provided) that can be used as image thumbnails.

      These regions preserve as much content as possible from the analyzed image, with priority given to detected faces.'
    properties:
      values:
        type: array
        description: A list of crop regions.
        minItems: 1
        items:
          $ref: '#/definitions/CropRegion'
        x-ms-identifiers: []
    required:
    - values
  ImagePoint:
    type: object
    description: Represents the coordinates of a single pixel in the image.
    properties:
      x:
        type: integer
        format: int32
        description: The horizontal x-coordinate of this point, in pixels. Zero values corresponds to the left-most pixels in the image.
        minimum: 0
      y:
        type: integer
        format: int32
        description: The vertical y-coordinate of this point, in pixels. Zero values corresponds to the top-most pixels in the image.
        minimum: 0
    required:
    - x
    - y
  DetectedPerson:
    type: object
    description: Represents a person detected in an image.
    properties:
      boundingBox:
        $ref: '#/definitions/ImageBoundingBox'
        description: A rectangular boundary where the person was detected.
        readOnly: true
      confidence:
        type: number
        format: float
        description: 'A score, in the range of 0 to 1 (inclusive), representing the confidence that this detection was accurate.

          Higher values indicating higher confidence.'
        minimum: 0
        maximum: 1
        readOnly: true
    required:
    - boundingBox
    - confidence
  CaptionResult:
    type: object
    description: Represents a generated phrase that describes the content of the whole image.
    properties:
      confidence:
        type: number
        format: float
        description: 'A score, in the range of 0 to 1 (inclusive), representing the confidence that this description is accurate.

          Higher values indicating higher confidence.'
        minimum: 0
        maximum: 1
      text:
        type: string
        description: The text of the caption.
        minLength: 1
    required:
    - confidence
    - text
parameters:
  Azure.Core.Foundations.ApiVersionParameter:
    name: api-version
    in: query
    description: The API version to use for this operation.
    required: true
    type: string
    minLength: 1
    x-ms-parameter-location: method
    x-ms-client-name: apiVersion
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'