Adobe Substance 3D API
Generate 3D object composites, render 3D scenes, and run Substance 3D material and model operations through the Firefly Services REST API.
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/refs/heads/main/openapi/_original/adobe-substance-3d-api-openapi.yml