Share via

Remote Rendering - Create Conversion

  • Reference
Service:
Mixed Reality
API Version:
2021-01-01

Creates a conversion using an asset stored in an Azure Blob Storage account.

PUT {endpoint}/accounts/{account_id}/conversions/{conversion_id}?api-version=2021-01-01

URI Parameters

Name In Required Type Description
account_id
 path True

string

uuid

The Azure Remote Rendering account ID.
conversion_id
 path True

string

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.
endpoint
 path True

string

The endpoint to use e.g. https://remoterendering.eastus.mixedreality.azure.com. A list can be found at https://docs.microsoft.com/azure/remote-rendering/reference/regions.
api-version
 query True

string

The API version to be used with the HTTP request.

Request Header

Name Required Type Description
Authorization True

string

A bearer token returned by the Mixed Reality Secure Token Service. See https://docs.microsoft.com/azure/remote-rendering/how-tos/tokens for details.

Request Body

Name Required Type Description
settings True

conversion_settings

Conversion settings describe the origin of input files and destination of output files.

Responses

Name Type Description
200 OK

conversion

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: string
201 Created

conversion

Created. A new conversion was created.

Headers

MS-CV: string
400 Bad Request

error_response

Bad Request. Returned error object describes which issues occurred.

Headers

MS-CV: string
401 Unauthorized

Unauthorized. Missing or invalid authorization.

Headers

  • MS-CV: string
  • WWW-Authenticate: string
403 Forbidden

Forbidden. Authorization insufficient for given resource.

Headers

MS-CV: string
429 Too Many Requests

Too Many Requests. The rate limit has been exceeded. Retry the request after the duration given in the Retry-After header.

Headers

  • MS-CV: string
  • Retry-After: integer
500 Internal Server Error

error_response

Internal Error. Server has encountered an internal error. Retrying the request may produce successful results.
Other Status Codes

error_response

Conflict. A conversion already exists. An error object describes which issues occurred.

Headers

MS-CV: string

Security

Authorization

A bearer token returned by the Mixed Reality Secure Token Service. See https://docs.microsoft.com/azure/remote-rendering/how-tos/tokens for details.

Type: apiKey
In: header

Examples

Create a conversion

Sample request

PUT https://remoterendering.eastus.mixedreality.azure.com/accounts/30ea64bd-100f-4bf0-adc9-29fa45d4880c/conversions/contoso-conversion-fbc3646c-0b97-4553-81ca-6fae2bfb754e?api-version=2021-01-01

{
  "settings": {
    "inputLocation": {
      "storageContainerUri": "https://contosostorage01.blob.core.windows.net/arrinput",
      "blobPrefix": "models/",
      "relativeInputAssetPath": "house.fbx"
    },
    "outputLocation": {
      "storageContainerUri": "https://contosostorage01.blob.core.windows.net/arroutput",
      "blobPrefix": "conversionOutput/fbc3646c-0b97-4553-81ca-6fae2bfb754e",
      "outputAssetFilename": "convertedHouse.arrAsset"
    }
  }
}

Sample response

Status code:
201 
MS-CV: dKEFmka2kkSlDmp/af+sOw
{
  "id": "contoso-conversion-fbc3646c-0b97-4553-81ca-6fae2bfb754e",
  "creationTime": "2021-01-01T11:11:11.111Z",
  "settings": {
    "inputLocation": {
      "storageContainerUri": "https://contosostorage01.blob.core.windows.net/arrinput",
      "blobPrefix": "models/",
      "relativeInputAssetPath": "house.fbx"
    },
    "outputLocation": {
      "storageContainerUri": "https://contosostorage01.blob.core.windows.net/arroutput",
      "blobPrefix": "conversionOutput/fbc3646c-0b97-4553-81ca-6fae2bfb754e",
      "outputAssetFilename": "convertedHouse.arrAsset"
    }
  },
  "status": "NotStarted",
  "error": null
}
Status code:
200 
MS-CV: dKEFmka2kkSlDmp/af+sOw
{
  "id": "contoso-conversion-fbc3646c-0b97-4553-81ca-6fae2bfb754e",
  "creationTime": "2021-01-01T11:11:11.111Z",
  "settings": {
    "inputLocation": {
      "storageContainerUri": "https://contosostorage01.blob.core.windows.net/arrinput",
      "blobPrefix": "models/",
      "relativeInputAssetPath": "house.fbx"
    },
    "outputLocation": {
      "storageContainerUri": "https://contosostorage01.blob.core.windows.net/arroutput",
      "blobPrefix": "conversionOutput/fbc3646c-0b97-4553-81ca-6fae2bfb754e",
      "outputAssetFilename": "convertedHouse.arrAsset"
    }
  },
  "status": "NotStarted",
  "error": null
}
Status code:
400 
MS-CV: dKEFmka2kkSlDmp/af+sOw
{
  "error": {
    "code": "BadRequest",
    "message": "The request was malformed."
  }
}
Status code:
409 
MS-CV: dKEFmka2kkSlDmp/af+sOw
{
  "error": {
    "code": "Conflict",
    "message": "A resource already exists under the given ID."
  }
}
Status code:
401 
WWW-Authenticate: Bearer error="invalid_token"
MS-CV: dKEFmka2kkSlDmp/af+sOw
Status code:
403 
MS-CV: dKEFmka2kkSlDmp/af+sOw
Status code:
429 
Retry-After: 15
MS-CV: dKEFmka2kkSlDmp/af+sOw
Status code:
500 
MS-CV: dKEFmka2kkSlDmp/af+sOw
{
  "error": {
    "code": "InternalServerError",
    "message": "An internal server error occurred."
  }
}

Definitions

Name Description
conversion

The properties of the conversion.
conversion_input_settings

Conversion input settings describe the origin of conversion input.
conversion_output_settings

Conversion output settings describe the destination of conversion output.
conversion_settings

Conversion settings describe the origin of input files and destination of output files.
conversion_status

The status of the conversion. Terminal states are 'Cancelled', 'Failed', and 'Succeeded'.
create_conversion_settings

Request to start a conversion
error

The error object containing details of why the request failed.
error_response

The error response containing details of why the request failed.
Output

Information about the output of a successful conversion. Only present when the status of the conversion is 'Succeeded'.

conversion

The properties of the conversion.

Name Type Description
creationTime

string

The time when the conversion was created. Date and time in ISO 8601 format.
error

error

The error object containing details about the conversion failure.
id

string

The ID of the conversion supplied when the conversion was created.
output

Output

Information about the output of a successful conversion. Only present when the status of the conversion is 'Succeeded'.
settings

conversion_settings

Conversion settings describe the origin of input files and destination of output files.
status

conversion_status

The status of the conversion. Terminal states are 'Cancelled', 'Failed', and 'Succeeded'.

conversion_input_settings

Conversion input settings describe the origin of conversion input.

Name Type Description
blobPrefix

string

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.
relativeInputAssetPath

string

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.
storageContainerReadListSas

string

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.
storageContainerUri

string

The URI of the Azure blob storage container containing the input model.

conversion_output_settings

Conversion output settings describe the destination of conversion output.

Name Type Description
blobPrefix

string

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.
outputAssetFilename

string

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
storageContainerUri

string

The URI of the Azure blob storage container where the result of the conversion should be written to.
storageContainerWriteSas

string

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.

conversion_settings

Conversion settings describe the origin of input files and destination of output files.

Name Type Description
inputLocation

conversion_input_settings

Conversion input settings describe the origin of conversion input.
outputLocation

conversion_output_settings

Conversion output settings describe the destination of conversion output.

conversion_status

The status of the conversion. Terminal states are 'Cancelled', 'Failed', and 'Succeeded'.

Name Type Description
Cancelled

string

The conversion was cancelled. This is a terminal state.
Failed

string

The conversion has failed. Check the 'error' field for more details. This is a terminal state.
NotStarted

string

The conversion was created but hasn't started.
Running

string

The conversion is running.
Succeeded

string

The conversion has succeeded. Check the 'output' field for output asset location. This is a terminal state.

create_conversion_settings

Request to start a conversion

Name Type Description
settings

conversion_settings

Conversion settings describe the origin of input files and destination of output files.

error

The error object containing details of why the request failed.

Name Type Description
code

string

Error code.
details

error[]

An array of details about specific errors that led to this reported error.
innerError

error

An object containing more specific information than the current object about the error.
message

string

A human-readable representation of the error.
target

string

The target of the particular error (e.g., the name of the property in error).

error_response

The error response containing details of why the request failed.

Name Type Description
error

error

The error object containing details of why the request failed.

Output

Information about the output of a successful conversion. Only present when the status of the conversion is 'Succeeded'.

Name Type Description
outputAssetUri

string

URI of the asset generated by the conversion process.