Composites

Generate 3D object composite

Changed on

Generate a 3D Object Composite with the Substance 3D API.

post/v1/composites/compose

Request

  • Base URL: https://s3d.adobe.io
  • URL: https://s3d.adobe.io/v1/composites/compose
  • Auth: HTTP bearer and API key in header x-api-key

Query parameters

waitboolean

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.

Headers

X-User-Tokenstring

A user token referencing the user's individual account, obtained using their credentials.

Request body

$schemastring uri

A URL to the JSON schema for this object.

cameraNamestring

Name of an existing camera in the source 3D scene. The camera has to be defined in the scene.

contentClass'art' | 'photo'

Class of content to generate.

customModelIdstring

ID of the custom model to be used for the generation. You can retrieve your custom model ID (assetId) with the Firefly retrieve custom model endpoint (https://developer.adobe.com/firefly-services/docs/firefly-api/api/#operation/getCustomModels).

enableGroundPlaneboolean

Enable the auto-generated ground plane under the hero asset. This is useful if the 3D scene contains only a hero asset, without additional elements.

environmentExposurenumber double

Exposure, in EV (0=neutral).

heroAssetstring required

Name of an existing 'hero asset' in the source 3D scene. The asset has to be defined in the scene.

lightingSeedsinteger[]

Optional seeds to be used to generate the lighting for the scene. The first seed will be used with the first seed of the background, the second one with the second seed of the background and so on. Background seeds must be defined and the number of lighting seeds should equal the number of background seeds. If not set, random seeds will be used. You will be able to retrieve the seeds used for the generation in the output details of the job.

modelVersion'image3_fast' | 'image4_standard' | 'image4_ultra'

Model version to be used to generate the background image with Adobe Firefly.

numVariationsinteger

The number of variations to generate. numVariations will default to the number of seeds, or to 1 if seeds is not specified.

promptstring required

Prompt to be used to generate the background image with Adobe Firefly.

sceneFilestring

The path of the scene file in sources. If value is null, the first found scene file will be used.

seedsinteger[]

Optional seed value to be used to generate the background image with Adobe Firefly. A seed ensures consistent background image generation. If seed is not set, a random seed will be used. Retrieve the seed used for the generation in the output details of the job. If specified with numVariations, the number of seeds must be the equal to numVariations.

styleImagestring

Optional 'style image' to be used to generate the background. The style image has to be present in sources.

Example request

{
  "cameraName": "main_camera",
  "heroAsset": "bottle",
  "prompt": "french style kitchen with a glass bottle sitting on an empty wooden table window on the left focal length 50mm",
  "sources": [
    {
      "url": {
        "url": "https://cdn.substance3d.com/v2/files/public/compositing_table_bottle.glb"
      }
    }
  ]
}

Response

Accepted

$schemastring uri

A URL to the JSON schema for this object.

bugReportUrlstring required

URL to report a bug about this job.

errorstring

Potential error that happened during the job processing.

idstring required

Unique identifier of the job.

statusstring required

Status of the job. Can be not_started, running, succeeded, or failed.

urlstring required

URL to fetch/poll for job result in case the job is not finished yet.

Example response

{
  "$schema": "https://s3d.adobe.io/schemas/restv1beta.ComposeSceneResponse.json",
  "result": {
    "outputSpace": {
      "$schema": "https://s3d.adobe.io/schemas/rest_base.Space.json"
    }
  }
}

Changes

  • a734f2b0003eRevision changes
    • warning

      removed the request property

    • info

      added the new optional header request parameter X-User-Token

    • info

      added the new optional request property

  • c56d1c657fa8Revision changes
    • breaking

      the response property / became nullable for the status

    • breaking

      the response property / became optional for the status