Uploading Assets

Learn how assets are uploaded and accessed by Substance 3D APIs.

Overview

Substance 3D APIs require assets like 3D models, scenes, and other materials. Assets must be uploaded and then the sources for those assets are specified in sources in the API request body.

Options for defining a source for asset files are:

Use a Space: Substance 3D API offers an endpoint to upload locally stored assets to a digital container called a Space.
Use URLs: Use public URLs from services like GitHub or Adobe.
Use Frame.io: Frame.io folders can provide access to multiple files.

This page describes the advantages and details for each of these source types.

Using Spaces

A Space is a virtual container for managing assets. Several file entries can be defined in a single Space, and you can reuse an output Space containing the files generated by a previously executed job.

To create a Space:

Upload local assets using the API endpoint for creating a Space. This operation generates a Space ID to use in other Substance 3D API calls.
Execute a job that requires merging assets from different sources.

To use a Space as a source, define it with its ID:

{
  "space": {
    "id": "s-example-6ba8-4ca6-842d-898057bf5dbc"
  }
}
Copied to your clipboard
{
  "space": {
    "id": "s-example-6ba8-4ca6-842d-898057bf5dbc"
  }
}

Structure and lifecycle

Consider a Space as a file system, with a root directory and subdirectories. The Substance 3D API backend works with Spaces to both retrieve input assets and store generated resources.

A Space is an immutable and temporary storage that expires after 6 hours. For each asset file in the Space, a pre-signed URL is generated where the results of the job can be downloaded for a limited time.

A pre-signed URL expires after 30 minutes. A new pre-signed URL can be obtained by calling the Space endpoint again.

By default, only the owner of a Space has permission to access it.

Space response

After a successful file upload, the response contains details for the newly created Space:

id: A unique Space identifier. This is the ID used to reference the Space in API calls.
url: The URL of the Space.
archiveUrl: The URL of the archive containing all files from the Space.
files: An array of all asset files available in the Space.

{
  "id": "s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc",
  "url": "https://s3d.adobe.io/v1/spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc",
  "archiveUrl": "https://s3d.adobe.io/v1/presigned-spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc/zip?x-s3d-presigned-token=<auto_generated_token>",
  "files": [
    {
      "name": "WaterBottle.glb",
      "size": 8961340,
      "url": "https://s3d.adobe.io/v1/presigned-spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc/files/WaterBottle.glb?x-s3d-presigned-token=<auto_generated_token>"
    }
  ]
}
Copied to your clipboard
{
  "id": "s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc",
  "url": "https://s3d.adobe.io/v1/spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc",
  "archiveUrl": "https://s3d.adobe.io/v1/presigned-spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc/zip?x-s3d-presigned-token=<auto_generated_token>",
  "files": [
    {
      "name": "WaterBottle.glb",
      "size": 8961340,
      "url": "https://s3d.adobe.io/v1/presigned-spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc/files/WaterBottle.glb?x-s3d-presigned-token=<auto_generated_token>"
    }
  ]
}

Using URLs

Assets can be retrieved from remote storage, like GitHub or a CDN, by using a URL. Each URL must point to a single resource.

Directories or archives ARE NOT supported.

Only these domains are supported:

adobe.com
adobe.io
adobesensei.io
amazonaws.com
frame.io
github.com
githubusercontent.com
googleapis.com
substance3d.com
substance3d.io
windows.net
zapier.com

To use a URL as a source, see this example to retrieve a 3D model from GitHub:

{
  "url": {
    "url": "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/WaterBottle/glTF-Binary/WaterBottle.glb"
  }
}
Copied to your clipboard
{
  "url": {
    "url": "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/WaterBottle/glTF-Binary/WaterBottle.glb"
  }
}

Using Frame.io

A Frame.io source can define several file entries from a Frame.io folder. All files present in the Frame.io folder are available for the job to process.

A Frame.io access token is required.

{
  "frame.io": {
    "folderId": "97ea16ad-1cf6-46c0-8982-ffbd4e2afc27",
    "accessToken": "<FRAME_IO_ACCESS_TOKEN>"
  }
}
Copied to your clipboard
{
  "frame.io": {
    "folderId": "97ea16ad-1cf6-46c0-8982-ffbd4e2afc27",
    "accessToken": "<FRAME_IO_ACCESS_TOKEN>"
  }
}

Using multiple sources

With multiple sources specified in a job definition, all assets are retrieved and then merged into a new Space.

In this case, it can be handy to define the source mount point to preserve a specific file hierarchy and avoid file conflicts (for example, two different sources containing files with the same name).

Mount points

As an example, say we want to run a 3D Render job using assets from two different locations: a 3D model stored on a CDN, and textures files stored in a Frame.io folder. The 3D model is configured to load the textures files from a textures directory.

In that case, we can define the different sources' mountPoint to indicate that these assets need to be in a specific folder:

{
  "sources": [
    {
      // destination folder
      "mountPoint": "/",
      // location of the 3D model file
      "url": {
        "url": "https://<a-cdn-url>/3dmodel.glb"
      },
    },
    {
      // destination folder
      "mountPoint": "/textures",
      // location of the texture files (e.g., texture.png)
      "frame.io": {
        "folderId": "408ee4ee-9204-4fc2-987b-2077e4ae30e0",
        "accessToken": "<frameio-access-token>"
      }
    }
  ]
}
Copied to your clipboard
{
  "sources": [
    {
      // destination folder
      "mountPoint": "/",
      // location of the 3D model file
      "url": {
        "url": "https://<a-cdn-url>/3dmodel.glb"
      },
    },
    {
      // destination folder
      "mountPoint": "/textures",
      // location of the texture files (e.g., texture.png)
      "frame.io": {
        "folderId": "408ee4ee-9204-4fc2-987b-2077e4ae30e0",
        "accessToken": "<frameio-access-token>"
      }
    }
  ]
}

These assets will be merged to create a Space with the following structure:

├── textures
│  └── texture.png
└── 3dmodel.glb
Copied to your clipboard
├── textures
│  └── texture.png
└── 3dmodel.glb

Authentication

Asynchronous Jobs

Last updated 7/23/2025

Was this helpful?

Yes