Resources

API – Asset Creation and Updating

API Base URL: https://api-platform.vntana.com

For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation hereNote: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the workspaces one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Workspace.

A key integration with the Platform is access to the core VNTANA feature, management of your Digital Assets, simply referred to as an Asset. With the API endpoints involved in Asset creation, you can automate the process of uploading files for Optimization, updating existing Assets, and downloading the stored files. Additionally, when coupled with Webhooks that monitor the conversion status of newly created 3D Assets you can reduce the amount of API calls made and more directly track an individual 3D files optimization status. For more information on Webhooks view this guide

As with all endpoints in the VNTANA Admin API, you must first properly authenticate, generating a Refresh Token as below. View this guide for a more complete look at authentication.

  1. Log in using an Authentication Key or email / password.

    • Returns an x-auth-token in the Response Headers.

  2. Retrieve a list of Organizations and store the needed Organization’s UUID.

    • Pass the x-auth-token from Step 1 in the Request Headers.

      1
      { ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token }
    • This step can be skipped if the Organization UUID is already stored locally.

  3. Generate a Refresh Token for the Organization.

    • Pass the x-auth-token from Step 1 in the Request Headers.

      1
      2
      3
      4
      {
      ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token
      ‘organizationUuid’ : ‘string’
      }
    • Returns the Refresh Token as the Response Header x-auth-token.

  4. Retrieve a list of Workspaces and store the needed UUID.

    • Pass the x-auth-token in the Request Headers.

    • This step can be skipped if the Workspace UUID is already stored locally.

  5. Generate a Refresh Token for the Workspace (Organization Admin / Owner users must skip this step).

    • Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Client UUID’s.

      1
      2
      3
      4
      5
      {
      ‘x-auth-token’ : ‘Bearer ‘ + refreshToken,
      ‘organizationUuid’ : ‘string’,
      ‘clientUuid’ : ‘string’
      }
    • Returns the Refresh Token as the Response Header x-auth-token.

Creating an Asset

The process of creating an Asset involves three key endpoints. First, the actual Asset must be created. On the VNTANA Platform an Asset is merely a container which can be viewed / accessed which holds the original files, any metadata set by you at Asset creation or update, and in the case of 3D files also stores the optimized formats and shows the optimized GLB in the VNTANA viewer. The endpoint for this first step is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
Method: POST
Endpoint: /v1/products
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“attributes” : {},
“publishToStatus” : “DRAFT” or “LIVE_INTERNAL” or “LIVE_PUBLIC”,
“status” : “DRAFT” or “LIVE_INTERNAL”,
“clientUuid” : “{{clientUuid}}”,
“description” : “”,
“locationsUuids” : [],
“modelOpsParameters” : {
“DRACO_COMPRESSION” : {
“enabled” : “true”
},
“OPTIMIZATION” : {
“desiredOutput” : “AUTO”,
“obstructedGeometry” : “true”,
“poly” : “50000”,
“forcePolygonCount” : “false”
},
“PIVOT_POINT_ALIGNMENT”: {
“pivotPoint”: “bottom-center” “or” “center”
},
“TEXTURE_COMPRESSION” : {
“lossless” : “true”,
“maxDimension” : “2048”,
“aggression” : “3”,
“useKTX” : “false”,
“bakeAmbientOcclusion” : “true”,
“amientOcclusionStrength” : “1”,
“ambientOcclusionRadius” : “5”,
“ambientOcclusionResolution” : “1024”
}
},
“name” : “{{name}}”,
“pipelineUuid” : “{{pipelineUuid}}”,
“presetUuid” : “”,
“tagsUuids” : [],
“assetType” : “THREE_D”,
“projectsUuids” : [ “string” ],
“project” : { … } or null
}

Important: autoPublish has been replaced by publishToStatus with possible values “DRAFT”, “LIVE_INTERNAL”, and “LIVE_PUBLIC”. Additionally, the parameter status is intended for use cases when you need to create an empty Asset (no associated file) but still want the Asset to be set to LIVE_INTERNAL and thus be accessible via the API.

The /v1/products endpoint can accept data on Projects to automatically link the Asset to any Projects or even create a new one. The projectsUuids parameter can take a list of projectUuids to link the Asset with. The project parameter can be used to simultaneously create a new Project and link the asset to, as well as creating subprojects if desired.

The project parameter contains all the info you’d need set up a new project including sub-projects. See below for the parameters that are included in this parameter. Note: if you do not wish to include any project data in your Asset creation, either pass null or completely exclude the parameter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
“name”: “string”,
“description”: “string”,
“parentUuid”: “string”,
“thumbnailUuid”: “string”,
“status”: “DRAFT”,
“locationsUuids”: [],
“tagsUuids”: [],
“attributes”: {},
“productsUuids”: [
“string”
],
“publishProductsToStatus”: true,
“subProjects”: [
{
“name”: “string”,
“description”: “string”,
“parentUuid”: “string”,
“thumbnailUuid”: “string”,
“status”: “DRAFT”,
“locationsUuids”: [],
“tagsUuids”: [],
“attributes”: {},
“productsUuids”: [
“string”
],
“publishProductsToStatus”: true
}
],
“clientUuid”: “string”
}

Another key parameter is the pipelineUuid. This refers to the Pipeline you select when creating an asset on the Platform and is required. If you do not already know the pipelineUuid you need to use, you can retrieve the list of Pipeline’s using the below example.

1
2
3
Method: GET
Endpoint: /v1/pipelines
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
{
“success”: true,
“errors”: [],
“response”: {
“pipelines”: [
{
“name”: “No Baking”,
“uuid”: “664a5d17-18d0-4bed-86b6-ab89Bcfa0b23”
},
{
“name”: “3D Scan”,
“uuid”: “fa2dc262-a785-4b19-b36a-2dae7449b7bb”
},
{
“name”: “Apparel – Tiled Textures”,
“uuid”: “c4a964c8-2203-4d02-ba37-4601ea6d157b”
},
{
“name”: “Browzwear”,
“uuid”: “87d414ec-e1f3-4fe3-a5f9-ac4b9cdc51f1”
},
{
“name”: “CLO”,
“uuid”: “39cc77c7-8456-48d0-a3dc-ce961f9cbb03”
},
{
“name”: “Convert Only”,
“uuid”: “0bea6387-243a-474c-aece-ca152a3d3b2b”
},
{
“name”: “Custom Jewelry”,
“uuid”: “30032bc3-5303-473b-80cf-07cdb26d8be5”
},
{
“name”: “Force Baking”,
“uuid”: “876f8604-8864-4d2e-8452-5c76fe443f4a”
},
{
“name”: “Industrial”,
“uuid”: “aebca294-3e48-4aef-8257-c2a7769de001”
},
{
“name”: “JigSpace”,
“uuid”: “5e0812d5-0989-4993-b490-dd6cd35d7213”
},
{
“name”: “Keyshot”,
“uuid”: “1167c16c-f777-43fd-a2a2-2806f8a46a4e”
},
{
“name”: “Other”,
“uuid”: “2453de9a-ecf5-418e-9e9d-dd0f85adc904”
},
{
“name”: “ParaView”,
“uuid”: “30a9395d-d98b-4c39-aacb-73ba2c33c155”
},
{
“name”: “Preserve UVs”,
“uuid”: “fd1953cb-cfa5-48bd-a267-af110d36daca”
},
{
“name”: “Preserve Meshes and UVs”,
“uuid”: “957e8b6e-7b41-477d-9a42-a12cc598d136”
},
{
“name”: “Preserve Nodes and Materials”,
“uuid”: “f1df30f6-0166-44e0-be07-b3c7aaf8792b”
},
{
“name”: “Stitch Baking Only”,
“uuid”: “02f2d6c8-10ac-49af-b6a7-cc7de9789e11”
},
{
“name”: “Unreal”,
“uuid”: “1be91cf2-7656-4b84-a08f-1278c466c19a”
},
{
“name”: “Wanna”,
“uuid”: “c39dddde-a357-4934-821c-9a646ab50368”
},
{
“name”: “Wanna – Bags Extended 3D Functionality”,
“uuid”: “26f1ceea-1db3-4f61-95d2-f06cdb5ede5a”
}
]
}
}

A successful request will return the Asset’s information including UUID.

An example of the Response Body from a successful Asset creation request.
1
2
3
4
5
6
7
8
9
{
“success”: true,
“errors”: [],
“response”: {
“uuid”: “some-uuid”,
“name”: “Test Creation”,
“productSessionUuId”: “some-uuid”
}
}

With the asset successfully created, a Signed URL must be generated using the UUID.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Method: POST
Endpoint: /v1/storage/upload/clients/products/asset/sign-url
Headers: {
‘x-auth-token’ : ‘Bearer ‘ + refreshToken,
‘Origin’ : ‘https://api-platform.vntana.com’,
}
Body: {
“clientUuid” : “{{clientUuid}}”,
“productUuid” : “{{productUuid}}”,
“resourceSettings” : {
“contentType” : “application/octet-stream”,
“originalName” : “original-file-name”,
“originalSize” : 0
}
}

This endpoint also requires the size in bytes of the file to be uploaded, as well as the name of the file. Finally, the file can be uploaded using the newly generated signed url as the endpoint as follows:

1
2
3
4
5
6
7
Method: PUT
Endpoint: signed-url from previous endpoint
Headers: {
‘Origin’ : ‘https://api-platform.vntana.com’,
‘Content-Length’ : 0
}
Body: File binary data must be streamed.

Once the file has been successfully uploaded, if it is a 3D model it will take some time to optimize depending on the complexity of the 3D model’s geometry and / or file size, but will have a conversion status of COMPLETED once it is ready to be published and the viewer can be loaded externally. An empty or processing asset will remain in Draft until an asset is finished optimizing. To find out the conversion status you can use the search endpoint (Search guide) and use the statuses parameter or set up a Webhook that subscribes to the Asset events related to conversion status (product events). View this guide to learn more about integrating with Webhooks. Note: only Assets in the Live Internal or Live Public state can be searched for via the API, Draft Assets will be hidden from the results.

Postman - Create Asset

To test this process, you can use the following Postman Collection. You can view a general guide on using our collections here, but overall you will need to set the necessary global variables found within the collection and decide which form of authentication you wish to use (key or email / pass). It is set to run as one complete collection, however if you wish to run each endpoint individually you need only activate the deactivated headers and ensure the global variables or local variables are set for each endpoint.

Once again, the final endpoint requires the size of the file in bytes, and the file data must be streamed. In Postman, you must select the ‘binary’ Body data type and set the file. Additionally, you may need to permit Postman to upload files from outside of the Postman workspace as this setting may not be the default. Simply go to File > Settings, and in the General tab look for Working Directory to turn on ‘Allow reading files outside working directory’.

Create Asset Collection

Updating an Asset

In addition to creating an Asset, you can update existing Assets (so long as they are not currently being processed by the Optimizer). This will allow you to either add metadata such as tags, attributes, or a description, make changes to data such as the Asset’s name, or upload a new / fixed 3D model to have it Optimized. The data passed to the endpoint is similar to that of Asset creation, however it does require the UUID of the Asset to update, and it must be in a Live state.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
Method: PUT
Endpoint: /v1/products
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“attributes”: {},
“publishToStatus”: “DRAFT” or “LIVE_INTERNAL” or “LIVE_PUBLIC”,
“status” : “DRAFT” or “LIVE_INTERNAL”,
“clientUuid”: “string”,
“deleteAsset”: true,
“description”: “string”,
“locationsUuids”: [],
“modelOpsParameters”: {
“DRACO_COMPRESSION” : {
“enabled” : “true”
},
“OPTIMIZATION” : {
“desiredOutput” : “AUTO”,
“obstructedGeometry” : “true”,
“poly” : “50000”,
“forcePolygonCount” : “false”
},
“PIVOT_POINT_ALIGNMENT”: {
“pivotPoint”: “bottom-center” “or” “center”
},
“TEXTURE_COMPRESSION” : {
“lossless” : “true”,
“maxDimension” : “2048”,
“aggression” : “3”,
“useKTX” : “false”,
“bakeAmbientOcclusion” : “true”,
“amientOcclusionStrength” : “1”,
“ambientOcclusionRadius” : “5”,
“ambientOcclusionResolution” : “1024”
}
},
“name”: “string”,
“pipelineUuid”: “string”,
“presetUuid”: “string”,
“tagsUuids”: [
“string”
],
“uuid”: “string”,
“project” : None,
“assetType” : “THREE_D”,
“projectsUuids” : [ “string” ]
}

Important: autoPublish has been replaced by publishToStatus with possible values “DRAFT”, “LIVE_INTERNAL”, and “LIVE_PUBLIC”. Additionally, the parameter status is intended for use cases when you need to create an empty Asset (no associated file) but still want the Asset to be set to LIVE_INTERNAL and thus be accessible via the API.

The endpoints for this are almost exactly the same as creating an asset with the only difference being the use of the PUT endpoint Update Asset instead of POST endpoint Create Asset. The collection includes the endpoints to generate a signed URL and upload the file, though it is possible to just update the data of an Asset and leave the file in tact, so running those endpoints is not necessary. If the deleteAsset parameter is set to true it will leave the Asset empty unless you follow up with the file upload.

Just like with the Create endpoint, you can add data to create a new Project and link the updated Asset using the project parameter. This parameter must either be null or contain a structure like below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
“name”: “string”,
“description”: “string”,
“parentUuid”: “string”,
“thumbnailUuid”: “string”,
“status”: “DRAFT”,
“locationsUuids”: [],
“tagsUuids”: [],
“attributes”: {},
“productsUuids”: [
“string”
],
“publishProductsToStatus”: true,
“subProjects”: [
{
“name”: “string”,
“description”: “string”,
“parentUuid”: “string”,
“thumbnailUuid”: “string”,
“status”: “DRAFT”,
“locationsUuids”: [],
“tagsUuids”: [],
“attributes”: {},
“productsUuids”: [
“string”
],
“publishProductsToStatus”: true
}
],
“clientUuid”: “string”
}

Update Asset Collection

Publish Status

When publishing your 3D to the VNTANA Platform, there are three main states in which the Asset can live. Depending on the state of an Asset, the functionality available both via the Admin API and directly on the Platform may be limited. The three states are: Draft, Live Internal,  and Live Public. In addition to differences in available functions, there is a cost difference associated with them, for more info on the VNTANA Pricing see this page.

Draft

The ‘free’ state, you can have unlimited Assets on the platform in the Draft state and will only incur charges for a given Asset if it is placed in Live Internal or Live Public once during a billing cycle. In this state, the following applies:

  • View the Optimized asset on the Platform.
    • The viewer will not load in external sites making Draft assets non-shareable.
  • Download the Original 3D asset.
    • You cannot download any of the optimized versions, however it will sill optimize allowing you to preview the result in the provided viewer on the Platform.
  • You will not be able to search for the Asset via the API. 
Live Internal

The ‘private’ paid status, this will allow you the same functionality as the Draft status with the added functionality of downloading the Optimized assets. In this state, the following applies:

  • View the Optimized asset on the Platform.
    • The viewer will not load in external sites.
  • Download the Original and Optimized assets.
  • Full access via the Admin API.
Live Public

The ‘public’ paid status, this will allow full functionality for the asset. In this state, the following applies:

  • View the Optimized asset on the Platform and share/embed the viewer externally.
  • Download the Original and Optimized assets, as well as generate a public share link to allow others to download.
  • Full access via the Admin API.

Note: While the Live Internal and Live Public are separate states and both can trigger a charge, they are not charged separately. You will be charged no more than once per asset and can swap between Live Internal and Live Public without incurring additional charges.

Publishing w/o 3D Asset

When utilizing a workflow which sees the creation of a multitude of Assets before their 3D files are available to upload, it is important to still be able to retrieve these Assets via the API to later edit or upload their files. In order to accomplish this, an additional parameter needs to be passed in the Asset creation body called status with a value of LIVE_INTERNAL. This will ensure the Asset behaves the same as a Live Internal asset which has a 3D file as normally an empty Asset can’t be in a Live state without a file.

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.

Tap the magnifying glass to the left of your screen to search our resources.