Generate 3D Object Composite

Combine 3D objects with AI-generated content using the Generate 3D Object Composite API.

Overview

Learn how to create compelling images by combining 3D models with AI-generated content using the Generate 3D Object Composite API. This guide walks you through the process of uploading assets, configuring compositing parameters, and generating final images.

Prerequisites

• You'll need a Substance 3D API Client ID and Access Token. learn how to retrieve them in the Authentication Guide.
• A command line tool to transfer data, such as cURL.

Step 1 - Upload source assets

1. Download the sample assets:

   • 3D Scene (compositing_table_bottle.glb)

2. To upload the 3D scene file to a new digital storage Space, use the /spaces endpoint and define the asset as a --form parameter in the request. Run the following command to create the new Space:

Copy
curl --url https://s3d.adobe.io/v1/spaces \
--header 'Authorization: Bearer $S3D_FF_SERVICES_ACCESS_TOKEN' \
--form '.=@compositing_table_bottle.glb'
Copied to your clipboard
curl --url https://s3d.adobe.io/v1/spaces \
--header 'Authorization: Bearer $S3D_FF_SERVICES_ACCESS_TOKEN' \
--form '.=@compositing_table_bottle.glb'

The result is a JSON response that contains the id of the new Space. This ID is the assets' source in the job definition.

Sample Response

Copy
{
  "id": "{GENERATED_SPACE_ID}",
  "files": [...],
  ...
}
Copied to your clipboard
{
  "id": "{GENERATED_SPACE_ID}",
  "files": [...],
  ...
}

Step 2 - Define assets sources

Create a payload.json file and reference the Space ID (<generated_space_id>) in the sources array:

Copy
{
  "sources": [
    {
      "space": {
        "id": "<generated_space_id>"
      }
    }
  ]
}
Copied to your clipboard
{
  "sources": [
    {
      "space": {
        "id": "<generated_space_id>"
      }
    }
  ]
}

Step 3 - Set the compositing parameters

To perform a compositing job, define:

• The hero asset name (the asset that should be rendered) from your scene file. bottle in this example.
• The camera name from your scene file. main_camera in this example.
• A prompt that describes the content of the AI-generated environment that will be composited with your 3D asset.

In this example, the 3D scene contains two models:

• a bottle model (hero asset) to be rendered.
• a table model, used to match the 3D scene layout in the generated background image.

With this information, append the following parameters to your payload.json file:

Copy
{
  "sources": [
    {
      "space": {
        "id": "<generated_space_id>"
      }
    }
  ],
  "heroAsset": "bottle",
  "cameraName": "main_camera",
  "prompt": "french style kitchen with empty wooden table window on the left focal length 50mm"
}
Copied to your clipboard
{
  "sources": [
    {
      "space": {
        "id": "<generated_space_id>"
      }
    }
  ],
  "heroAsset": "bottle",
  "cameraName": "main_camera",
  "prompt": "french style kitchen with empty wooden table window on the left focal length 50mm"
}

Step 4 - Execute the API request

It's time to execute the compositing API request, using the job definition from your payload.json file.

Send a request to the Compose API:

Copy
curl -vX POST https://s3d.adobe.io/v1/composites/compose \
-d @payload.json \
--header "Content-Type: application/json" \
--header 'Authorization: Bearer $S3D_FF_SERVICES_ACCESS_TOKEN'
Copied to your clipboard
curl -vX POST https://s3d.adobe.io/v1/composites/compose \
-d @payload.json \
--header "Content-Type: application/json" \
--header 'Authorization: Bearer $S3D_FF_SERVICES_ACCESS_TOKEN'

The response will be similar to this:

Copy
{
  "$schema": "https://s3d.adobe.io/schemas/ComposeSceneResponse.json",
  // The URL to poll the job's status and result
  "url": "https://s3d.adobe.io/v1/jobs/1727790895129-0",
  // A unique identifier for the job
  "id": "1727790895129-0",
  "status": "running"
}
Copied to your clipboard
{
  "$schema": "https://s3d.adobe.io/schemas/ComposeSceneResponse.json",
  // The URL to poll the job's status and result
  "url": "https://s3d.adobe.io/v1/jobs/1727790895129-0",
  // A unique identifier for the job
  "id": "1727790895129-0",
  "status": "running"
}

Step 5 - Download the rendered images

After sending the API request, you'll obtain a response containing an URL that can be used to fetch the job's progress and result.

Since jobs are asynchronous, their result isn't available immediately. The job URL must be polled until the status indicates either succeeded or failed.

Copy
curl --url {JOB_URL} \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $S3D_FF_SERVICES_ACCESS_TOKEN'
Copied to your clipboard
curl --url {JOB_URL} \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $S3D_FF_SERVICES_ACCESS_TOKEN'

If the job succeeds, the response will contain an additional result property with information about the generated resources.

Copy
{
  "$schema": "https://s3d.adobe.io/schemas/ComposeSceneResponse.json",
  "url": "https://s3d.adobe.io/v1/jobs/1727790895129-0",
  "id": "1727790895129-0",
  "status": "succeeded",
  "result": {
    "outputs:": [
      {
        "image": {
          "seed": 63000,
          "url": "https://s3d.adobe.io/v1/spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc/files/render0000.png?x-s3d-presigned-token=<auto_generated_token>"
        },
        ...
      }
    ],
    "promptHasDeniedWords": false,
    "promptHasBlockedArtists": false,
    "outputSpace": {
      "url": "https://s3d.adobe.io/v1/spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc",
      "id": "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": "render0000.png",
          "size": 3894406,
          "url": "https://s3d.adobe.io/v1/spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc/files/render0000.png?x-s3d-presigned-token=<auto_generated_token>"
        },
        ...
      ]
    }
  }
}
Copied to your clipboard
{
  "$schema": "https://s3d.adobe.io/schemas/ComposeSceneResponse.json",
  "url": "https://s3d.adobe.io/v1/jobs/1727790895129-0",
  "id": "1727790895129-0",
  "status": "succeeded",
  "result": {
    "outputs:": [
      {
        "image": {
          "seed": 63000,
          "url": "https://s3d.adobe.io/v1/spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc/files/render0000.png?x-s3d-presigned-token=<auto_generated_token>"
        },
        ...
      }
    ],
    "promptHasDeniedWords": false,
    "promptHasBlockedArtists": false,
    "outputSpace": {
      "url": "https://s3d.adobe.io/v1/spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc",
      "id": "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": "render0000.png",
          "size": 3894406,
          "url": "https://s3d.adobe.io/v1/spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc/files/render0000.png?x-s3d-presigned-token=<auto_generated_token>"
        },
        ...
      ]
    }
  }
}

Copy
{
  "$schema": "https://s3d.adobe.io/schemas/ComposeSceneResponse.json",
  "url": "https://s3d.adobe.io/v1/jobs/1727790895129-0",
  "id": "1727790895129-0",
  "status": "failed",
  "error": "error message"
}
Copied to your clipboard
{
  "$schema": "https://s3d.adobe.io/schemas/ComposeSceneResponse.json",
  "url": "https://s3d.adobe.io/v1/jobs/1727790895129-0",
  "id": "1727790895129-0",
  "status": "failed",
  "error": "error message"
}

To download the rendered images, you can use the pre-signed URLs included in the response (result.outputs[].image.url), or find the rendered images URL from the list of files in the response (result.outputSpace.files[].url).

Copy
curl -O --url https://s3d.adobe.io/v1/spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc/files/render0000.png?x-s3d-presigned-token=<auto_generated_token>
Copied to your clipboard
curl -O --url https://s3d.adobe.io/v1/spaces/s-b93fa62b-6ba8-4ca6-842d-898057bf5dbc/files/render0000.png?x-s3d-presigned-token=<auto_generated_token>

Deepen your understanding

Now that you completed this tutorial, visit its API Reference to explore more advanced use cases of 2D/3D compositing.

Last updated 7/23/2025

Was this helpful?

Yes

No