swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Describe API
schemes:
- https
tags:
- name: Describe
paths:
  /describe:
    post:
      description: This operation generates a description of an image in human readable language with complete sentences.  The description is based on a collection of content tags, which are also returned by the operation. More than one description can be generated for each image.  Descriptions are ordered by their confidence score. All descriptions are in English. 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.
      operationId: microsoftAzureDescribeimage
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: maxCandidates
        in: query
        description: Maximum number of candidate descriptions to be returned.  The default is 1.
        type: string
        required: false
        default: '1'
      - $ref: '#/parameters/ServiceLanguage'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
      responses:
        '200':
          description: Image description object.
          schema:
            $ref: '#/definitions/ImageDescription'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/ComputerVisionError'
      x-ms-examples:
        Successful Describe request:
          $ref: ./examples/SuccessfulDescribeWithUrl.json
      summary: Microsoft Azure Post Describe
      tags:
      - Describe
definitions:
  ImageDescription:
    type: object
    description: A collection of content tags, along with a list of captions sorted by confidence level, and image metadata.
    properties:
      description:
        x-ms-client-flatten: true
        $ref: '#/definitions/ImageDescriptionDetails'
  ImageMetadata:
    type: object
    description: Image metadata
    properties:
      width:
        type: integer
        format: int32
        description: Image width
      height:
        type: integer
        format: int32
        description: Image height
      format:
        type: string
        description: Image format
  ComputerVisionError:
    type: object
    required:
    - code
    - message
    properties:
      code:
        type: string
        description: The error code.
        enum:
        - InvalidImageUrl
        - InvalidImageFormat
        - InvalidImageSize
        - NotSupportedVisualFeature
        - NotSupportedImage
        - InvalidDetails
        - NotSupportedLanguage
        - BadArgument
        - FailedToProcess
        - Timeout
        - InternalServerError
        - Unspecified
        - StorageException
        x-ms-enum:
          name: ComputerVisionErrorCodes
          modelAsString: false
      message:
        type: string
        description: A message explaining the error reported by the service.
      requestId:
        type: string
        description: A unique request identifier.
  ImageDescriptionDetails:
    type: object
    description: A collection of content tags, along with a list of captions sorted by confidence level, and image metadata.
    properties:
      tags:
        type: array
        description: A collection of image tags.
        items:
          type: string
      captions:
        type: array
        description: A list of captions, sorted by confidence level.
        items:
          $ref: '#/definitions/ImageCaption'
      requestId:
        type: string
        description: Id of the REST API request.
      metadata:
        $ref: '#/definitions/ImageMetadata'
  ImageCaption:
    type: object
    description: An image caption, i.e. a brief description of what the image depicts.
    properties:
      text:
        type: string
        description: The text of the caption
      confidence:
        type: number
        format: double
        description: The level of confidence the service has in the caption
parameters:
  ServiceLanguage:
    name: language
    in: query
    description: The desired language for output generation. If this parameter is not specified, the default value is "en".Supported languages:en - English, Default. es - Spanish, ja - Japanese, pt - Portuguese, zh - Simplified Chinese.
    type: string
    required: false
    x-ms-parameter-location: method
    x-nullable: false
    default: en
    enum:
    - en
    - es
    - ja
    - pt
    - zh
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'