Microsoft Azure Conversion API

openapi: 3.2.0
info:
  description: 'Describing the Azure Remote Rendering REST API for rendering sessions and asset conversions.


    All requests to these APIs must be authenticated using the Secure Token Service as described in the Azure Remote rendering documentation chapter about authentication.'
  title: Microsoft Azure MixedRealityRemoteRendering Conversion API
  version: 2021-01-01-preview
security:
- MrcBearerAuth: []
tags:
- name: Conversion
paths:
  /accounts/{account_id}/conversions/{conversion_id}:
    put:
      operationId: microsoftAzureRemoterenderingCreateconversion
      x-ms-examples:
        Create a conversion:
          $ref: ./examples/CreateConversion.json
      parameters:
      - $ref: '#/components/parameters/api_version'
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/conversion_id'
      responses:
        '200':
          description: OK. Indicates that there was already a conversion with the same settings present. This is expected when a conversion creation is retried.
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversion'
        '201':
          description: Created. A new conversion was created.
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversion'
        '400':
          description: Bad Request. Returned error object describes which issues occurred.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              schema:
                type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '409':
          description: Conflict. A conversion already exists. An error object describes which issues occurred.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              schema:
                type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      tags:
      - Conversion
      summary: Microsoft Azure Creates A Conversion Using An Asset Stored In An Azure Blob…
      description: Needs a more full description created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_conversion_settings'
        description: Request body configuring the settings for an asset conversion.
        required: true
    get:
      operationId: microsoftAzureRemoterenderingGetconversion
      parameters:
      - $ref: '#/components/parameters/api_version'
      - $ref: '#/components/parameters/account_id'
      - $ref: '#/components/parameters/conversion_id'
      x-ms-examples:
        Get a single conversion by ID:
          $ref: ./examples/GetConversion.json
      responses:
        '200':
          description: OK.
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            Retry-After:
              description: Time in seconds when the status of this conversion should be polled again
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversion'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              schema:
                type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '404':
          description: Not found. No conversion with the provided conversion ID exists.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              schema:
                type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      tags:
      - Conversion
      summary: Microsoft Azure Gets The Status Of A Particular Conversion
      description: Needs a more full description created.
  /accounts/{account_id}/conversions:
    get:
      operationId: microsoftAzureRemoterenderingListconversions
      parameters:
      - $ref: '#/components/parameters/api_version'
      - $ref: '#/components/parameters/account_id'
      x-ms-examples:
        List conversions:
          $ref: ./examples/ListConversions.json
      responses:
        '200':
          description: OK.
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting issues.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversion_list'
        '401':
          description: Unauthorized. Missing or invalid authorization.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting errors to the Azure Remote Rendering team.
              schema:
                type: string
            WWW-Authenticate:
              description: Describes the error encountered while trying to authenticate the resource.
              schema:
                type: string
        '403':
          description: Forbidden. Authorization insufficient for given resource.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting errors to the Azure Remote Rendering team.
              schema:
                type: string
        '429':
          description: Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting errors to the Azure Remote Rendering team.
              schema:
                type: string
            Retry-After:
              description: The minimum number of seconds to wait before not getting this response anymore.
              schema:
                type: integer
        '500':
          description: Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
          x-ms-error-response: true
          headers:
            MS-CV:
              description: Microsoft Correlation Vector. Include this value when reporting errors to the Azure Remote Rendering team.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_response'
      x-ms-pageable:
        itemName: conversions
        nextLinkName: '@nextLink'
      tags:
      - Conversion
      summary: Microsoft Azure Gets A List Of All Conversions
      description: Needs a more full description created.
components:
  schemas:
    conversion:
      description: The properties of the conversion.
      properties:
        id:
          type: string
          description: The ID of the conversion supplied when the conversion was created.
        settings:
          $ref: '#/components/schemas/conversion_settings'
        output:
          type: object
          description: Information about the output of a successful conversion. Only present when the status of the conversion is 'Succeeded'.
          properties:
            outputAssetUri:
              type: string
              description: URI of the asset generated by the conversion process.
              format: uri
              example: https://contoso.blob.core.windows.net/arr/architecture-output/house.arrAsset
              readOnly: true
          readOnly: true
        error:
          description: The error object containing details about the conversion failure.
          type:
          - object
          - 'null'
          $ref: '#/components/schemas/error'
          example: null
        status:
          $ref: '#/components/schemas/conversion_status'
        creationTime:
          type: string
          description: The time when the conversion was created. Date and time in ISO 8601 format.
          format: date-time
      required:
      - id
      - settings
      - status
      - error
      - creationTime
      type: object
    conversion_list:
      description: List of conversions.
      properties:
        conversions:
          items:
            $ref: '#/components/schemas/conversion'
          type: array
          description: The list of conversions.
        '@nextLink':
          description: If more conversions are available this field will contain a URL where the next batch of conversions can be requested. This URL will need the same authentication as all calls to the Azure Remote Rendering API.
          type: string
          readOnly: true
      required:
      - conversions
      type: object
    create_conversion_settings:
      description: Request to start a conversion
      properties:
        settings:
          $ref: '#/components/schemas/conversion_settings'
      required:
      - settings
      type: object
    conversion_input_settings:
      properties:
        storageContainerUri:
          type: string
          description: The URI of the Azure blob storage container containing the input model.
          format: uri
          example: https://contosostorage01.blob.core.windows.net/arrinput
        storageContainerReadListSas:
          type: string
          description: An Azure blob storage container shared access signature giving read and list access to the storage container. Optional. If not provided, the Azure Remote Rendering account needs to be linked with the storage account containing the blob container. See https://docs.microsoft.com/azure/remote-rendering/how-tos/create-an-account#link-storage-accounts for details. For security purposes this field will never be filled out in responses bodies.
        blobPrefix:
          type: string
          description: Only Blobs starting with this prefix will be downloaded to perform the conversion. Optional. If not provided, all Blobs from the container will be downloaded.
          example: models/
        relativeInputAssetPath:
          type: string
          description: The relative path starting at blobPrefix (or at the container root if blobPrefix is not provided) to the input model. Must point to a file with a supported file format ending. See https://docs.microsoft.com/azure/remote-rendering/how-tos/conversion/model-conversion for details.
          example: house.fbx
      required:
      - storageContainerUri
      - relativeInputAssetPath
      type: object
      description: Conversion input settings describe the origin of conversion input.
    error:
      description: The error object containing details of why the request failed.
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: A human-readable representation of the error.
        details:
          type: array
          items:
            $ref: '#/components/schemas/error'
          description: An array of details about specific errors that led to this reported error.
          readOnly: true
        target:
          description: The target of the particular error (e.g., the name of the property in error).
          type: string
          readOnly: true
        innerError:
          type: object
          $ref: '#/components/schemas/error'
          description: An object containing more specific information than the current object about the error.
          readOnly: true
      type: object
      required:
      - code
      - message
    conversion_status:
      description: The status of the conversion. Terminal states are 'Cancelled', 'Failed', and 'Succeeded'.
      enum:
      - NotStarted
      - Running
      - Cancelled
      - Failed
      - Succeeded
      type: string
      x-ms-enum:
        name: conversion_status
        modelAsString: true
        values:
        - value: NotStarted
          description: The conversion was created but hasn't started.
        - value: Running
          description: The conversion is running.
        - value: Cancelled
          description: The conversion was cancelled. This is a terminal state.
        - value: Failed
          description: The conversion has failed. Check the 'error' field for more details. This is a terminal state.
        - value: Succeeded
          description: The conversion has succeeded. Check the 'output' field for output asset location. This is a terminal state.
    conversion_settings:
      description: Conversion settings describe the origin of input files and destination of output files.
      properties:
        inputLocation:
          $ref: '#/components/schemas/conversion_input_settings'
        outputLocation:
          $ref: '#/components/schemas/conversion_output_settings'
      required:
      - inputLocation
      - outputLocation
      type: object
    conversion_output_settings:
      properties:
        storageContainerUri:
          type: string
          description: The URI of the Azure blob storage container where the result of the conversion should be written to.
          format: uri
          example: https://contosostorage01.blob.core.windows.net/arroutput
        storageContainerWriteSas:
          type: string
          description: An Azure blob storage container shared access signature giving write access to the storage container. Optional. If not provided, the Azure Remote Rendering account needs to be linked with the storage account containing the blob container. See https://docs.microsoft.com/azure/remote-rendering/how-tos/create-an-account#link-storage-accounts for details. For security purposes this field will never be filled out in responses bodies.
        blobPrefix:
          type: string
          description: A prefix which gets prepended in front of all files produced by the conversion process. Will be treated as a virtual folder. Optional. If not provided, output files will be stored at the container root.
          example: conversionOutput/fbc3646c-0b97-4553-81ca-6fae2bfb754e
        outputAssetFilename:
          type: string
          description: The file name of the output asset. Must end in '.arrAsset'. Optional. If not provided, file name will the same name as the input asset, with '.arrAsset' extension
          example: house.arrAsset
      required:
      - storageContainerUri
      type: object
      description: Conversion output settings describe the destination of conversion output.
    error_response:
      description: The error response containing details of why the request failed.
      properties:
        error:
          description: The error object containing details of why the request failed.
          type: object
          $ref: '#/components/schemas/error'
      type: object
      required:
      - error
  parameters:
    conversion_id:
      description: An ID uniquely identifying the conversion for the given account. The ID is case sensitive, can contain any combination of alphanumeric characters including hyphens and underscores, and cannot contain more than 256 characters.
      in: path
      name: conversion_id
      required: true
      x-example: contoso-conversion-fbc3646c-0b97-4553-81ca-6fae2bfb754e
      x-ms-parameter-location: method
      schema:
        type: string
    api_version:
      name: api-version
      in: query
      description: The API version to be used with the HTTP request.
      required: true
      x-example: 2021-01-01-preview
      x-ms-parameter-location: method
      schema:
        type: string
    account_id:
      name: account_id
      description: The Azure Remote Rendering account ID.
      in: path
      required: true
      x-example: 30ea64bd-100f-4bf0-adc9-29fa45d4880c
      x-ms-parameter-location: method
      schema:
        type: string
        format: uuid
  securitySchemes:
    MrcBearerAuth:
      in: header
      name: Authorization
      type: apiKey
      description: A bearer token returned by the Mixed Reality Secure Token Service. See https://docs.microsoft.com/azure/remote-rendering/how-tos/tokens for details.
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'