Adobe Substance 3D API
Render, convert and automate 3D assets at scale through the Adobe Substance 3D API in Firefly Services, covering scene rendering, material application, model conversion and batch 3D asset production.
OpenAPI Specification
openapi: 3.1.0
info:
description: REST API for Adobe Substance 3D - Firefly Services.
title: Adobe Substance 3D API - Firefly Services
version: 1.0.0
servers:
- url: 'https://s3d.adobe.io'
paths:
/v1/composites/compose:
post:
operationId: v1/composites/compose
summary: Generate 3D object composite
description: Generate a 3D Object Composite with the Substance 3D API.
parameters:
- name: X-User-Token
in: header
description: 'A user token referencing the user''s individual account, obtained using their credentials.'
schema:
type: string
- name: wait
in: query
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
schema:
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
type: boolean
default: false
explode: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/restv1.ComposeSceneRequest'
responses:
'202':
description: Accepted
headers:
Retry-After:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.ComposeSceneResponse'
'400':
description: Bad Request
content:
application/json:
examples:
empty_input_body:
value:
error_code: empty_input_body
message: ''
invalid_json:
value:
error_code: invalid_json
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'403':
description: Forbidden
content:
application/json:
examples:
access_error:
value:
error_code: access_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'408':
description: Request Timeout
content:
application/json:
examples:
timeout_error:
value:
error_code: timeout_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'415':
description: Unsupported Media Type
content:
application/json:
examples:
invalid_content_type:
value:
error_code: invalid_content_type
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'422':
description: Unprocessable Entity
content:
application/json:
examples:
validation_error:
value:
error_code: validation_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'429':
description: Too Many Requests
content:
application/json:
examples:
rate_limited:
value:
error_code: rate_limited
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'500':
description: Internal Server Error
content:
application/json:
examples:
runtime_error:
value:
error_code: runtime_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
tags:
- Composites
x-s3d-public: true
'/v1/jobs/{id}': {}
/v1/scenes/assemble:
post:
operationId: v1/scenes/assemble
summary: Create 3D scene
description: Assemble a 3D scene with the Substance 3D API.
parameters:
- name: wait
in: query
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
schema:
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
type: boolean
default: false
explode: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.CreateSceneRequest'
responses:
'202':
description: Accepted
headers:
Retry-After:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.CreateSceneResponse'
'400':
description: Bad Request
content:
application/json:
examples:
empty_input_body:
value:
error_code: empty_input_body
message: ''
invalid_json:
value:
error_code: invalid_json
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'403':
description: Forbidden
content:
application/json:
examples:
access_error:
value:
error_code: access_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'408':
description: Request Timeout
content:
application/json:
examples:
timeout_error:
value:
error_code: timeout_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'415':
description: Unsupported Media Type
content:
application/json:
examples:
invalid_content_type:
value:
error_code: invalid_content_type
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'422':
description: Unprocessable Entity
content:
application/json:
examples:
validation_error:
value:
error_code: validation_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'429':
description: Too Many Requests
content:
application/json:
examples:
rate_limited:
value:
error_code: rate_limited
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'500':
description: Internal Server Error
content:
application/json:
examples:
runtime_error:
value:
error_code: runtime_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
tags:
- Scenes
x-s3d-public: true
/v1/scenes/convert:
post:
operationId: v1/scenes/convert
summary: Convert 3D files
description: Convert a 3D file into another 3D format with the Substance 3D API.
parameters:
- name: wait
in: query
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
schema:
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
type: boolean
default: false
explode: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.ModelConvertRequest'
responses:
'202':
description: Accepted
headers:
Retry-After:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.ModelConvertResponse'
'400':
description: Bad Request
content:
application/json:
examples:
empty_input_body:
value:
error_code: empty_input_body
message: ''
invalid_json:
value:
error_code: invalid_json
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'403':
description: Forbidden
content:
application/json:
examples:
access_error:
value:
error_code: access_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'408':
description: Request Timeout
content:
application/json:
examples:
timeout_error:
value:
error_code: timeout_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'415':
description: Unsupported Media Type
content:
application/json:
examples:
invalid_content_type:
value:
error_code: invalid_content_type
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'422':
description: Unprocessable Entity
content:
application/json:
examples:
validation_error:
value:
error_code: validation_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'429':
description: Too Many Requests
content:
application/json:
examples:
rate_limited:
value:
error_code: rate_limited
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'500':
description: Internal Server Error
content:
application/json:
examples:
runtime_error:
value:
error_code: runtime_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
tags:
- Scenes
x-s3d-public: true
/v1/scenes/describe:
post:
operationId: v1/scenes/describe
summary: Describe 3D scene
description: Describe a 3D scene.
parameters:
- name: wait
in: query
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
schema:
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
type: boolean
default: false
explode: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.SceneDescRequest'
responses:
'202':
description: Accepted
headers:
Retry-After:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.SceneDescResponse'
'400':
description: Bad Request
content:
application/json:
examples:
empty_input_body:
value:
error_code: empty_input_body
message: ''
invalid_json:
value:
error_code: invalid_json
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'403':
description: Forbidden
content:
application/json:
examples:
access_error:
value:
error_code: access_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'408':
description: Request Timeout
content:
application/json:
examples:
timeout_error:
value:
error_code: timeout_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'415':
description: Unsupported Media Type
content:
application/json:
examples:
invalid_content_type:
value:
error_code: invalid_content_type
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'422':
description: Unprocessable Entity
content:
application/json:
examples:
validation_error:
value:
error_code: validation_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'429':
description: Too Many Requests
content:
application/json:
examples:
rate_limited:
value:
error_code: rate_limited
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'500':
description: Internal Server Error
content:
application/json:
examples:
runtime_error:
value:
error_code: runtime_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
tags:
- Scenes
x-s3d-public: true
/v1/scenes/render:
post:
operationId: v1/scenes/render
summary: Render 3D object
description: Render a 3D object with the Substance 3D API.
parameters:
- name: wait
in: query
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
schema:
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
type: boolean
default: false
explode: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.RenderSceneRequest'
responses:
'202':
description: Accepted
headers:
Retry-After:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.RenderSceneResponse'
'400':
description: Bad Request
content:
application/json:
examples:
empty_input_body:
value:
error_code: empty_input_body
message: ''
invalid_json:
value:
error_code: invalid_json
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'403':
description: Forbidden
content:
application/json:
examples:
access_error:
value:
error_code: access_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'408':
description: Request Timeout
content:
application/json:
examples:
timeout_error:
value:
error_code: timeout_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'415':
description: Unsupported Media Type
content:
application/json:
examples:
invalid_content_type:
value:
error_code: invalid_content_type
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'422':
description: Unprocessable Entity
content:
application/json:
examples:
validation_error:
value:
error_code: validation_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'429':
description: Too Many Requests
content:
application/json:
examples:
rate_limited:
value:
error_code: rate_limited
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'500':
description: Internal Server Error
content:
application/json:
examples:
runtime_error:
value:
error_code: runtime_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
tags:
- Scenes
x-s3d-public: true
/v1/scenes/render-basic:
post:
operationId: v1/scenes/render-basic
summary: Render 3D object (basic version)
description: Render a 3D object (basic version) with the Substance 3D API.
parameters:
- name: wait
in: query
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
schema:
description: 'Blocking mode (acts like a synchronous API call). Wait for the result before returning. ⚠️ Some operations are long, please be sure to configure your client timeout settings accordingly.'
type: boolean
default: false
explode: false
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.RenderModelRequest'
responses:
'202':
description: Accepted
headers:
Retry-After:
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/restv1beta.RenderModelResponse'
'400':
description: Bad Request
content:
application/json:
examples:
empty_input_body:
value:
error_code: empty_input_body
message: ''
invalid_json:
value:
error_code: invalid_json
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'403':
description: Forbidden
content:
application/json:
examples:
access_error:
value:
error_code: access_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'408':
description: Request Timeout
content:
application/json:
examples:
timeout_error:
value:
error_code: timeout_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'415':
description: Unsupported Media Type
content:
application/json:
examples:
invalid_content_type:
value:
error_code: invalid_content_type
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'422':
description: Unprocessable Entity
content:
application/json:
examples:
validation_error:
value:
error_code: validation_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'429':
description: Too Many Requests
content:
application/json:
examples:
rate_limited:
value:
error_code: rate_limited
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'500':
description: Internal Server Error
content:
application/json:
examples:
runtime_error:
value:
error_code: runtime_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
tags:
- Scenes
x-s3d-public: true
/v1/spaces:
post:
operationId: createSpace_v1
summary: Create Space
description: Create a Space from 3D files.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
filename:
description: Filename of the file being uploaded.
type: string
format: binary
contentMediaType: application/octet-stream
name:
description: General purpose name for multipart form value.
type: string
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/rest_base.Space'
'400':
description: Bad Request
content:
application/json:
examples:
empty_input_body:
value:
error_code: empty_input_body
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'403':
description: Forbidden
content:
application/json:
examples:
access_error:
value:
error_code: access_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'408':
description: Request Timeout
content:
application/json:
examples:
timeout_error:
value:
error_code: timeout_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'413':
description: Request Entity Too Large
content:
application/json:
examples:
entity_too_large:
value:
error_code: entity_too_large
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'422':
description: Unprocessable Entity
content:
application/json:
examples:
validation_error:
value:
error_code: validation_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'429':
description: Too Many Requests
content:
application/json:
examples:
rate_limited:
value:
error_code: rate_limited
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'500':
description: Internal Server Error
content:
application/json:
examples:
runtime_error:
value:
error_code: runtime_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
tags:
- Spaces
x-s3d-public: true
'/v1/spaces/{id}': {}
/v1beta/3dmodels/convert: {}
/v1beta/3dmodels/render: {}
/v1beta/3dmodels/render-turntable: {}
/v1beta/3dscenes/compose: {}
/v1beta/3dscenes/create: {}
/v1beta/3dscenes/get-description: {}
/v1beta/3dscenes/render: {}
'/v1beta/jobs/{id}': {}
/v1beta/spaces: {}
'/v1beta/spaces/{id}': {}
'/v2/jobs/{id}': {}
/v2/spaces:
post:
operationId: createSpace_v2
summary: Create Space API
description: |
## Overview
The **Substance 3D API** provides a way to upload and temporarily store files.
Uploading files requires a **multipart/form-data** request to send data.
The request requires a **files** field containing a list of files. Each file's **filename** field can contain a filepath to specify where the file will be stored in the space.
Example for this files tree:
```
├── textures
│ ├── diffuse.png
│ └── normal.png
└── lighthouse.fbx
```
HTTP data relative to the previous files tree:
```HTTP
POST /spaces HTTP/1.1
Host: localhost:8080
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="files"; filename="lighthouse.fbx"
Content-Type: model/vnd.autodesk.fbx
(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="files"; filename="textures/diffuse.png"
Content-Type: image/png
(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="files"; filename="textures/normal.png"
Content-Type: image/png
(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--
```
Curl command to create this file tree:
```
curl -X POST https://s3d.adobe.io/v2/spaces \
-F "files=@Local/Path/To/The/Local/File/lighthouse.fbx;filename=lighthouse.fbx" \
-F "files=@Local/Path/To/The/Local/File/diffuse.png;filename=textures/diffuse.png" \
-F "files=@Local/Path/To/The/Local/File/normal.png;filename=textures/normal.png"
```
The result of the post is a **JSON** which contained the **id** of the space created.
Space **id** can be used into a space source to use space content as a source for API operations.
Example of a space source:
```json
{
"space": {
"id": "<space_id>"
}
}
```
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
files:
type: array
items:
contentMediaType: application/octet-stream
format: binary
type: string
minItems: 1
required:
- files
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/rest_base.Space'
'400':
description: Bad Request
content:
application/json:
examples:
empty_input_body:
value:
error_code: empty_input_body
message: ''
invalid_multipart:
value:
error_code: invalid_multipart
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'403':
description: Forbidden
content:
application/json:
examples:
access_error:
value:
error_code: access_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'408':
description: Request Timeout
content:
application/json:
examples:
timeout_error:
value:
error_code: timeout_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'413':
description: Request Entity Too Large
content:
application/json:
examples:
entity_too_large:
value:
error_code: entity_too_large
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'422':
description: Unprocessable Entity
content:
application/json:
examples:
validation_error:
value:
error_code: validation_error
message: ''
schema:
$ref: '#/components/schemas/ffapierrors.FFAPIError'
'429':
description: Too Many Requests
content:
application/json:
examples:
rate_limited:
value:
# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adobe-suite/refs/heads/main/openapi/adobe-suite-firefly-substance-3d-openapi.yaml