job
Creates a job to translate the specified source design from one format to another, generating derivatives of the source design. You can optionally:
- Extract selected parts of a design and export the set of geometries to the OBJ format.
- Generate different-sized thumbnails.
Follow the step-by-step tutorials for detailed instructions on how to use this operation to translate files, extract geometries, and generate thumbnails.
When the translation job runs, progress information and details of the generated derivatives are logged to a JSON file that is called a manifest. A manifest is typically created the first time you translate the source design. Thereafter the system updates the same manifest each time a translation job is executed for that source design. If necessary, you can set the x-ads-force
header to true
, which deletes the existing manifest and creates a fresh manifest. However, if you do so, all derivatives generated prior to this are deleted.
A translation job is asynchronous and runs as a background process. There is no need not keep the HTTP connection open until the job completes. Use Fetch Manifest to check for the job’s completion status.
Resource Information
Method and URI | POST https://developer.api.autodesk.com/modelderivative/v2/designdata/job |
Method and URI (EMEA) | POST https://developer.api.autodesk.com/modelderivative/v2/regions/eu/designdata/job |
Authentication Context | user context optional |
Required OAuth Scopes | data:read and (data:write or data:create ) |
Data Format | JSON |
Rate Limit | 500 calls per minute |
Request
Headers
Authorization* string | Must be Bearer <token> , where <token> is obtained via POST /authentication/v2/token |
Content-Type* string | Must be application/json |
region enum:string | Specifies where to store the manifest and derivatives. Possible values are:
Note:
|
x-ads-force bool |
|
x-ads-derivative-format enum:string | Specifies how to interpret the formats.advanced.objectIds request body attribute for OBJ output. Possible values are:
Note
|
Request
Body Structure
Attributes that Apply to All Outputs
input* object | An object describing the attributes of the source design. |
urn* string | The URL safe Base64 encoded URN of the source design.
Note: The URN is returned as the
objectID once you complete uploading the source design to APS. This value must be converted to a Base64 (URL Safe) encoded string before you can specify it for this attribute. |
compressedUrn bool |
|
rootFilename string | The file name of the top-level component of the source design. Mandatory if compressedUrn is set to true. |
checkReferences bool |
Set this attribute to true if the design specified by the |
output* object | An object describing the attributes of the requested derivatives. |
destination object | Note: This attribute is replaced by the |
region string | region header to specify what region to store outputs.
Note: This attribute is replaced by the |
formats* array: object | Group of requested formats/types. User can request multiple formats. |
type* string | The requested output types. Possible values: dwg , fbx , ifc , iges , obj , step , stl , svf , svf2 , thumbnail . For a list of supported types, call the List Supported Formats operation. |
misc object | Group of misc parameters |
workflow string | The workflow id created for a webhook, used to listen to Model Derivative events. It needs to be no more than 36 chars, and only ASCII, decimal and hyphen are accepted.
Refer to the tutorial Creating a Webhook and Listening to Events for details. |
workflowAttribute object | A user-defined JSON object, which you can use to set some custom workflow information. It needs to be less than 1KB and will be ignored if misc.workflow parameter is not set. |
Attributes that Apply to SVF or SVF2 Outputs
Case 1 - Input file type is not RVT, IFC, NWD, or VUE:
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Valid values are:
|
views* array: string | Possible values: 2d , 3d |
Case 2 - Input file type is DGN:
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Valid values are:
|
views* array:string | Possible values: 2d , 3d |
advanced object | A set of special options applicable when the input file type is DGN. |
requestedLinkageIDs array:integer | An array containing user data linkage IDs of the linkage data to be extracted from the DGN file. Linkage data is not extracted if you do not specify this attribute. |
Case 3 - Input file type is DWG:
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Valid values are:
|
views* array: string | Possible values: 2d , 3d |
advanced object | A set of special options applicable when the input file type is DWG. |
2dviews enum: string | The format that 2D views must be rendered to. Available options are:
|
Case 4 - Input file type is IFC:
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Valid values are:
|
views* array: string | Possible values: 2d , 3d |
advanced object | A set of special options applicable when the input file type is IFC. |
switchLoader bool | false . |
conversionMethod string | Specifies the IFC loader to use during translation. Available options are:
If both |
buildingStoreys string | Specifies how storeys are translated. Available options are:
Note These options do not apply when |
spaces string | Specifies how spaces are translated. Available options are:
Note These options do not apply when |
openingElements string | An option to be specified when the input file type is IFC.
Specifies how openings are translated. Available options are:
Note These options do not apply when |
Case 5 - Input file type is NWD:
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Valid values are:
|
views* array: string | Possible values: 2d , 3d |
advanced object | A set of special options applicable when the input file type is Navisworks. |
hiddenObjects bool | Specifies whether hidden objects must be extracted or not.
|
basicMaterialProperties bool | Specifies whether basic material properties must be extracted or not.
|
autodeskMaterialProperties bool | Specifies how to handle Autodesk material properties.
|
timelinerProperties bool | Specifies whether timeliner properties must be extracted or not.
|
Case 6 - Input file type is RVT:
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Valid values are:
|
views* array: string | Possible values: 2d , 3d |
advanced object | A set of special options applicable when the input file type is Revit. |
2dviews enum: string | The format that 2D views must be rendered to. Available options are:
|
extractorVersion enum: string | Specifies what version of the Revit translator/extractor to use. Possible values:
If this attribute is not specified, the system uses the current official release version. |
generateMasterViews bool | Generates master views when translating from the Revit input format to SVF. This option is ignored for all other input formats. This attribute defaults to false .
Master views are 3D views that are generated for each phase of the Revit model. A master view contains all elements (including “room” elements) present in the host model for that phase. The display name of a master view defaults to the name of the phase it is generated from. However, if a view with that name already exists, the Model Derivative service appends a suffix to the default display name. Notes:
|
materialMode string | Specifies the materials settings to apply to the generated derivatives. Available options are:
|
Case 7 - Input file type is VUE:
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Valid values are:
|
views* array: string | Possible values: 2d , 3d |
advanced object | A set of special options applicable when the input file type is VUE. |
hierarchy enum | Specifies how the hierarchy of items are determined.
Notes:
|
Attributes that Apply to Thumbnail Outputs
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Must be thumbnail for the thumbnail output type. |
advanced object | Advanced options for thumbnail type. |
width int | Set the width. Possible values: 100 , 200 , 400 |
height int | Set the height. Possible values: 100 , 200 , 400 |
Attributes that Apply to STL Outputs
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Must be stl for the STL output type. |
advanced object | Advanced options for stl output type. |
format string | Default format is binary . Possible values: binary , ascii |
exportColor bool | Color is exported by default. If set to true , color is exported. If set to false , color is not exported. |
exportFileStructure enum: string |
|
Attributes that Apply to STEP Outputs
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Must be step for the STEP output type. |
advanced object | Advanced options for step output type. |
applicationProtocol string | A STEP file can be generated with the following application protocols:
By default, |
tolerance float | Possible values: between 0 and 1 . By default it is set at 0.001. |
Attributes that Apply to IGES Outputs
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Must be iges for the IGES output type. |
advanced object | Advanced options for iges output type. |
tolerance float | Possible values: between 0 and 1 . By default it is set at 0.001. |
surfaceType string | Possible values: bounded , trimmed , wireframe . By default it is set to bounded surface. |
sheetType string | Export the sheet body to IGES open , shell , surface or wireframe . By default, it is set to surface . |
solidType string | Export the solid body to IGES solid , surface or wireframe . By default, it is set to solid . |
Attributes that Apply to OBJ Outputs
formats* object | A JSON object representing the requested output. types. |
type* string | The requested output type. Must be obj for the OBJ output type. |
advanced object | Advanced options for obj output type. |
exportFileStructure enum:string | Ignored for geometry extraction.
|
unit enum:string | Translate models into different units; this causes the values to change. For example, from millimeters (10, 123, 31) to centimeters (1.0, 12.3, 3.1). If the source unit or the unit you are translating into is not supported, the values remain unchanged.
Possible values:
Note that this feature does not support F3D files. |
modelGuid string | Required for geometry extraction. The model view ID (guid). Currently only valid for 3d views. |
objectIds array: int | Required for geometry extraction. List object ids to be translated. -1 will extract the entire model. Currently only valid for 3d views. |
Attributes that Apply to DWG Outputs
Note that when translating RVT to DWG, it only translates the selected
2D views of the model. You can choose which of the 2D views you need to translate (to DWG) through the Revit addon Publish Settings
. If nothing selected, all sheet views (if any) would be translated by default.
formats* object | A JSON object representing the requested output types. |
type* string | The requested output type. Must be dwg for the DWG output type. |
advanced object | Advanced options for dwg output type. |
exportSettingName string | The export settings should be one of the DWG Export settings name pre-saved in the document.
If the string is invalid, or the specified settings name is not found in the document, one of the following would be used according to the following priority.
Please refer to Export to DWG or DXF and Revit API Developers Guide in Revit help for details. |
Attributes that Apply to IFC Outputs
Note that when translating RVT to IFC, it does not matter whether or not there is a 3D view in the model. All the elements in the model would be translated to IFC.
formats* object | A JSON object representing the requested output. |
type* string | The requested output type. Must be ifc for the IFC output type. |
advanced object | Advanced options for ifc output type. |
exportSettingName string | The export settings should be one of the IFC Export settings pre-saved in the document.
If the string is invalid, or the specified settings are not found in the document, the system will use the default settings. The default settings are obtained by creating a Revit API object from the class IFCExportOptions.
The list of settings pre-saved in the document can be accessed from Revit dialog ‘Export IFC’. But there is currently no Revit API for getting this data from the document.
Please refer to Exporting to Industry Foundation Classes (IFC) and Revit API Developers Guide for more details.
|
Response
HTTP Status Code Summary
200 OK | Success. Note that you still need to check whether the asynchronous job is complete by calling the Fetch Manifest operation. |
201 CREATED | The requested file type has been previously generated and has not been replaced by the new source file. |
400 BAD REQUEST | Invalid request. E.g., the input URN format is invalid. |
401 UNAUTHORIZED | Invalid authorization header. |
403 FORBIDDEN | Access denied regardless of authorization status. |
404 NOT FOUND | Endpoint does not exist. |
406 NOT ACCEPTABLE | The request is not acceptable. E.g., the output type is not supported. |
409 CONFLICT | The request conflicts with a previous request that is still in progress. |
429 TOO MANY REQUEST | Rate limit exceeded (500 requests per minute); wait some time before retrying. |
500 INTERNAL SERVICE ERROR | Unexpected service interruption. |
Response
HTTP Headers
x-ads-app-identifier string | The service identifier comprise service name, version and environment. |
x-ads-startup-time string | The service startup time with data format EEE MMM dd HH:mm:ss Z yyyy . |
x-ads-duration string | The request duration in milliseconds. |
Response
Body Structure (200/201)
result string | reporting success status |
urn string | the urn identifier of the source file |
acceptedJobs array: object | list of the requested outputs |
output array: object | identical to the request body. For more information please see the request body structure above. |
Response
Body Structure (400)
diagnostics string | reason for failure |
Example 1
A successful attempt kicking off a job for the translation of an Inventor model to SVF2, where the source files are packaged as a single zip file (200).
Note: This request does not explicitly specify a region
header. So, the system assumes the default region, which is US
.
Request
curl -X 'POST' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer PtnrvrtSRpWwUi3407QhgvqdUVKL'
-v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/job' \
-d
'{
"input": {
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LnppcA",
"compressedUrn": true,
"rootFilename": "A5.iam"
},
"output": {
"formats": [
{
"type": "svf2",
"views": [
"2d",
"3d"
]
}
]
}
}'
Response
Status Code: 200 OK
Content-Type:application/json;charset=utf-8
Access-Control-Allow-Credentials:true
Access-Control-Allow-Origin:*
x-ads-app-identifier:platform-viewing-2016.05.03.1102.2f6bfbf-production
x-ads-startup-time:Wed May 11 14:03:54 CST 2016
x-ads-duration:280 ms
{
"result": "success",
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LnppcA",
"acceptedJobs": {
"output": {
"formats": [
{
"type": "svf2",
"views": [
"2d",
"3d"
]
}
]
}
}
}
Example 2
A successful attempt kicking off a job for the translation of an Inventor part file to SVF2. The derivatives are to be stored in the in the EMEA region.
Request
curl -X 'POST' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer PtnrvrtSRpWwUi3407QhgvqdUVKL...' \
-H 'region: EMEA' \
-v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/job' \
-d '{
"input": {
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6anBfZW1lYV9idWNrZXQvYm94LmlwdA=="
},
"output": {
"formats": [
{
"type": "svf2",
"views": [
"2d",
"3d"
]
}
]
}
}'
Response
Status Code: 200 OK
Content-Type:application/json;charset=utf-8
Access-Control-Allow-Credentials:true
Access-Control-Allow-Origin:*
x-ads-app-identifier:platform-viewing-2023.11.01.52.7902cdefa-production
x-ads-startup-time:Mon Nov 27 04:47:37 UTC 2023
x-ads-duration:1083 ms
{
"result": "success",
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6anBfZW1lYV9idWNrZXQvYm94LmlwdA",
"acceptedJobs": {
"output": {
"formats": [
{
"type": "svf2",
"views": [
"2d",
"3d"
]
]
}
}
}
Example 3
Illustrates what happens when you kick off a job for a source file that was translated previously (201).
Request
curl -X 'POST' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer PtnrvrtSRpWwUi3407QhgvqdUVKL' \
-H 'x-ads-force: false' -v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/job' \
-H 'region: US' \
-d '{
"input": {
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LnppcA",
"compressedUrn": true,
"rootFilename": "A5.iam"
},
"output": {
"formats": [
{
"type": "svf2",
"views": [
"2d",
"3d"
]
}
]
}
}'
Response
Status Code: 201 Created
Content-Type:application/json;charset=utf-8
Access-Control-Allow-Credentials:true
Access-Control-Allow-Origin:*
x-ads-app-identifier:platform-viewing-2016.05.03.1102.2f6bfbf-production
x-ads-startup-time:Wed May 11 14:03:54 CST 2016
x-ads-duration:280 ms
{
"result": "created",
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LnppcA",
"acceptedJobs": {
"formats": [
{
"type": "svf2",
"views": [
"2d",
"3d"
]
}
]
}
}
}
Example 4
A successful attempt at starting a job to export geometry corresponding to the specified object ids to the OBJ format (200).
Request
curl -X 'POST' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer PtnrvrtSRpWwUi3407QhgvqdUVKL' \
-v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/job' \
-d
'{
"input": {
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LnppcA"
},
"output": {
"formats": [
{
"type": "obj",
"advanced": {
"modelGuid": "4f981e94-8241-4eaf-b08b-cd337c6b8b1f",
"objectIds": [
2,
3,
4
]
}
}
]
}
}'
Response
Status Code: 200 OK
Content-Type:application/json;charset=utf-8
Access-Control-Allow-Credentials:true
Access-Control-Allow-Origin:*
x-ads-app-identifier:platform-viewing-2016.05.03.1102.2f6bfbf-production
x-ads-startup-time:Wed May 11 14:03:54 CST 2016
x-ads-duration:280 ms
{
"result": "success",
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LnppcA",
"acceptedJobs": {
"output": {
"destination": {
"region": "us"
},
"formats": [
{
"type": "obj",
"advanced": {
"modelGuid": "4f981e94-8241-4eaf-b08b-cd337c6b8b1f",
"objectIds": [
2,
3,
4
]
}
}
]
}
}
}
Example 5
A failed attempt to start a job for extracting geometry. The job request failed because the specified object ids are invalid (400).
Request
curl -X 'POST' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer PtnrvrtSRpWwUi3407QhgvqdUVKL' \
-v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/job' \
-d '{
"input": {
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LnppcA"
},
"output": {
"formats": [
{
"type": "obj",
"advanced": {
"modelGuid": "4f981e94-8241-4eaf-b08b-cd337c6b8b1f",
"objectIds": [
-2
]
}
}
]
}
}'
Response
Status Code: 400 Bad Request
Content-Type:application/json;charset=utf-8
x-ads-app-identifier:platform-viewing-2016.05.03.1102.2f6bfbf-production
x-ads-startup-time:Wed May 11 14:03:54 CST 2016
x-ads-duration:478 ms
x-ads-exception-id:53ff8a6f-a49c-460a-b48c-79862e7eddb5
x-ads-troubleshooting:Invalid Request
{
"diagnostic":"The values of 'objectIds' should be equal or greater than 0. You can also set the value as [-1] for getting the whole model."
}
Example 6
Successful creation of a job with webhook workflow specified (200)
Request
curl -X 'POST' \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer PtnrvrtSRpWwUi3407QhgvqdUVKL'
-v 'https://developer.api.autodesk.com/modelderivative/v2/designdata/job' \
-d
'{
"input": {
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LnppcA",
"compressedUrn": true,
"rootFilename": "A5.iam"
},
"misc": {
"workflow": "my-workflow-id",
"workflowAttribute": {
"myfoo": 33,
"projectId": "someURN",
"myobject": {
"nested": true
}
}
},
"output": {
"formats": [
{
"type": "svf",
"views": [
"2d",
"3d"
]
}
]
}
}'
Response
Status Code: 200 OK
Content-Type:application/json;charset=utf-8
Access-Control-Allow-Credentials:true
Access-Control-Allow-Origin:*
x-ads-app-identifier:platform-viewing-2016.05.03.1102.2f6bfbf-production
x-ads-startup-time:Wed May 11 14:03:54 CST 2016
x-ads-duration:280 ms
{
"result": "success",
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6bW9kZWxkZXJpdmF0aXZlL0E1LnppcA",
"acceptedJobs": {
"output": {
"formats": [
{
"type": "svf",
"views": [
"2d",
"3d"
]
}
]
}
}
}