openapi: 3.2.0
info:
  description: REST API for Adobe Substance 3D - Firefly Services.
  title: Adobe Substance 3D API - Firefly Services Composites API
  version: 1.0.0
servers:
- url: https://s3d.adobe.io
security:
- bearerAuth: []
  ApiKeyAuth: []
tags:
- name: Composites
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
components:
  schemas:
    restv1beta.ComposeSceneResponse:
      type: object
      properties:
        $schema:
          description: A URL to the JSON schema for this object.
          type: string
          format: uri
          examples:
          - https://s3d.adobe.io/schemas/restv1beta.ComposeSceneResponse.json
          readOnly: true
        bugReportUrl:
          description: URL to report a bug about this job.
          type: string
        error:
          description: Potential error that happened during the job processing.
          type: string
        id:
          description: Unique identifier of the job.
          type: string
        result:
          description: Result when the job is successfully finished.
          $ref: '#/components/schemas/restv1beta.ComposeSceneJobResult'
        status:
          description: Status of the job. Can be `not_started`, `running`, `succeeded`, or `failed`.
          type: string
        url:
          description: URL to fetch/poll for job result in case the job is not finished yet.
          type: string
      additionalProperties: false
      required:
      - url
      - id
      - status
      - bugReportUrl
    types.ComposeSceneSceneDetails:
      type: object
      properties:
        camera:
          description: Custom camera definition for the scene render. Mutually exclusive with 'cameraName' at the top level. Use this to define camera parameters programmatically instead of referencing a named camera from the 3D scene.
          $ref: '#/components/schemas/types.SceneCamera'
      additionalProperties: false
    restv1.ComposeSceneRequest:
      type: object
      properties:
        $schema:
          description: A URL to the JSON schema for this object.
          type: string
          format: uri
          examples:
          - https://s3d.adobe.io/schemas/restv1.ComposeSceneRequest.json
          readOnly: true
        cameraName:
          description: Name of an existing camera in the source 3D scene. The camera has to be defined in the scene.
          type: string
        contentClass:
          description: Class of content to generate.
          type: string
          default: photo
          enum:
          - art
          - photo
        customModelId:
          description: 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).
          type: string
        enableGroundPlane:
          description: 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.
          type: boolean
          default: false
        environment:
          description: Optional environment settings used for all variations. If omitted, an environment will be generated based on the background. If set, the `lightingSeeds` parameter will be ignored.
          $ref: '#/components/schemas/types.ComposeEnvironment'
        environmentExposure:
          description: Exposure, in EV (0=neutral).
          type: number
          format: double
          maximum: 10
          minimum: -10
        heroAsset:
          description: Name of an existing 'hero asset' in the source 3D scene. The asset has to be defined in the scene.
          type: string
          minLength: 1
        lightingSeeds:
          description: 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.
          type: array
          items:
            format: int64
            type: integer
          maxItems: 4
        modelVersion:
          description: Model version to be used to generate the background image with Adobe Firefly.
          type: string
          default: image4_ultra
          enum:
          - image3_fast
          - image4_standard
          - image4_ultra
        numVariations:
          description: The number of variations to generate. `numVariations` will default to the number of seeds, or to 1 if `seeds` is not specified.
          type: integer
          format: int64
          maximum: 4
          minimum: 1
        prompt:
          description: Prompt to be used to generate the background image with Adobe Firefly.
          type: string
          minLength: 1
        scene:
          description: Optional scene-level details, such as a custom camera.
          $ref: '#/components/schemas/types.ComposeSceneSceneDetails'
        sceneFile:
          description: The path of the scene file in `sources`. If value is null, the first found scene file will be used.
          type: string
        seeds:
          description: 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`.
          type: array
          items:
            format: int64
            type: integer
          maxItems: 4
        size:
          description: "The size of the image generations. The supported dimensions for image generations are: \n  | Dimensions | Description | \n  | -----------| ----- |\n  | { \"width\": 2048, \"height\": 2048} | Square (1:1) |\n  | { \"width\": 2304, \"height\": 1792 } | Landscape (4:3) |\n  | { \"width\": 1792, \"height\": 2304 } | Portrait (3:4) | \n  | { \"width\": 2688, \"height\": 1536 } | Widescreen (16:9) |  \n  | { \"width\": 1344, \"height\": 768 } |(7:4) |  \n  |{ \"width\": 1152, \"height\": 896 } |(9:7) |  \n  |{ \"width\": 896, \"height\": 1152 } |(7:9) |  \n  | { \"width\": 1024, \"height\": 1024} | Square (1:1) |"
          $ref: '#/components/schemas/types.OutputSize'
        sources:
          description: List of sources to aggregate and run the job against.
          type: array
          items:
            $ref: '#/components/schemas/rest_base.MountedSource'
          maxItems: 16
          minItems: 1
        styleImage:
          description: Optional 'style image' to be used to generate the background. The style image has to be present in `sources`.
          type: string
      additionalProperties: false
      examples:
      - 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
      required:
      - sources
      - prompt
      - heroAsset
    rest_base.SpaceFile:
      type: object
      properties:
        name:
          type: string
        size:
          type: integer
          format: int64
          minimum: 0
        url:
          type: string
      additionalProperties: false
      required:
      - url
      - name
      - size
    rest_base.SourceSpace:
      type: object
      properties:
        id:
          description: A space ID.
          type: string
      additionalProperties: false
      required:
      - id
    types.OutputSize:
      type: object
      properties:
        height:
          type: integer
          format: int64
          default: 1536
          maximum: 2688
          minimum: 1
        width:
          type: integer
          format: int64
          default: 2688
          maximum: 2688
          minimum: 1
      additionalProperties: false
      required:
      - width
      - height
    ffapierrors.FFAPIError:
      description: The error within the error response.
      type: object
      properties:
        $schema:
          description: A URL to the JSON schema for this object.
          type: string
          format: uri
          examples:
          - https://s3d.adobe.io/schemas/ffapierrors.FFAPIError.json
          readOnly: true
        error_code:
          description: Associated error code.
          type: string
        error_details:
          description: Optional list of individual error details.
          type: array
          items:
            type: object
        message:
          description: Error message.
          type: string
      additionalProperties: false
      required:
      - error_code
    rest_base.Space:
      type: object
      properties:
        $schema:
          description: A URL to the JSON schema for this object.
          type: string
          format: uri
          examples:
          - https://s3d.adobe.io/schemas/rest_base.Space.json
          readOnly: true
        expiry:
          description: time at which the space will be deleted
          type: string
          format: date-time
        files:
          description: List of all files contained in Space, ordered by name.
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/rest_base.SpaceFile'
        id:
          description: Unique identifier of this Space.
          type: string
        url:
          description: URL to the full description of this Space.
          type: string
        archiveUrl:
          description: URL to fetch the whole space as an archive (usually a ZIP file).
      additionalProperties: false
      required:
      - url
      - id
      - expiry
      - files
    types.ComposeEnvironment:
      type: object
      properties:
        file:
          description: Path of environment file in `sources`. If value is null, the environment file will be generated.
          type: string
        rotation:
          description: Controls the orientation of the environment map.
          $ref: '#/components/schemas/types.Rotation'
      additionalProperties: false
      required:
      - file
    types.TRS:
      type: object
      properties:
        rotation:
          $ref: '#/components/schemas/types.Rotation'
        scale:
          type:
          - array
          - 'null'
          items:
            format: double
            type: number
          maxItems: 3
          minItems: 3
        translation:
          type:
          - array
          - 'null'
          items:
            format: double
            type: number
          examples:
          - - 0
            - 0
            - 0
          maxItems: 3
          minItems: 3
      additionalProperties: false
      required:
      - translation
      - rotation
      - scale
    types.Rotation:
      type: object
      properties:
        euler:
          description: Euler angles in degrees.
          type: array
          items:
            format: double
            type: number
          examples:
          - - 0
            - 0
            - 0
          maxItems: 3
          minItems: 3
        quaternion:
          description: In W,X,Y,Z order.
          type: array
          items:
            format: double
            type: number
          examples:
          - - 1
            - 0
            - 0
            - 0
          maxItems: 4
          minItems: 4
      additionalProperties: false
    rest_base.MountedSource:
      type: object
      properties:
        frame.io:
          description: Fetch content from a Frame.io folder. ⚠️ All sources are exclusive.
          $ref: '#/components/schemas/rest_base.SourceFrameIO'
          deprecated: true
        mountPoint:
          description: Where to mount the content of the source in the virtual job working directory.
          type: string
          default: /
        next.frame.io:
          description: Fetch content from a next.frame.io folder. ⚠️ All sources are exclusive.
          $ref: '#/components/schemas/rest_base.SourceFrameIOV4'
        space:
          description: Read content from an existing space (can be another job's output, or uploaded manually with the space API). ⚠️ All sources are exclusive.'
          $ref: '#/components/schemas/rest_base.SourceSpace'
        url:
          description: Fetch content from a URL. ⚠️ All sources are exclusive.
          $ref: '#/components/schemas/rest_base.SourceURL'
      additionalProperties: false
    rest_base.SourceFrameIO:
      type: object
      properties:
        accessToken:
          description: Frame.io access token or Developer token. See https://developer.frame.io/docs/getting-started/authentication for obtaining a token.
          type: string
        folderId:
          description: Frame.io folder ID containing the assets. This should be the ID of the folder (not an asset ID). For best performance and to avoid [size limitations](/#what-is-the-maximum-size-of-assets-i-can-process), use the folder ID closest to your target assets. The system will retrieve all content from the specified folder, so choosing a parent folder with many subfolders may exceed the maximum retrieval size limit
          type: string
      additionalProperties: false
      required:
      - folderId
      - accessToken
    rest_base.SourceFrameIOV4:
      type: object
      properties:
        accessToken:
          description: Frame.io access token. See https://developer.adobe.com/frameio/guides/Authentication/ for obtaining a token.
          type: string
        accountId:
          description: Frame.io account ID. This is the account identifier for the next.frame.io account owner. To find your account ID, log in to next.frame.io, navigate to your inbox, and extract the UUID from the URL (e.g., in https://next.frame.io/inbox/abcdefgh-1234-1234-1234-abcdefghijk, the account ID is abcdefgh-1234-1234-1234-abcdefghijk)
          type: string
        folderId:
          description: Frame.io folder ID containing the assets. This should be the ID of the folder (not an asset ID). For best performance and to avoid [size limitations](/#what-is-the-maximum-size-of-assets-i-can-process), use the folder ID closest to your target assets. The system will retrieve all content from the specified folder, so choosing a parent folder with many subfolders may exceed the maximum retrieval size limit
          type: string
      additionalProperties: false
      required:
      - folderId
      - accountId
      - accessToken
    types.Warning:
      type: object
      properties:
        context:
          type: string
        message:
          type: string
      additionalProperties: false
      required:
      - context
      - message
    types.AzimuthAltitude:
      type: object
      properties:
        altitude:
          description: Altitude, in degrees, from -90 to 90 degrees.
          type: number
          format: double
          maximum: 90
          minimum: -90
        azimuth:
          description: Rotation around the vertical axis, in degrees.
          type: number
          format: double
        lookAt:
          description: Look at point coordinates.
          type:
          - array
          - 'null'
          items:
            format: double
            type: number
          maxItems: 3
          minItems: 3
        radius:
          description: Distance to the `lookAt` point.
          type: number
          format: double
          minimum: 0
      additionalProperties: false
      required:
      - azimuth
      - altitude
      - lookAt
      - radius
    restv1beta.ComposeSceneJobResult:
      type: object
      properties:
        outputSpace:
          $ref: '#/components/schemas/rest_base.Space'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/restv1beta.ComposeOutput'
        promptHasBlockedArtists:
          type: boolean
        promptHasDeniedWords:
          type: boolean
        warnings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/types.Warning'
      additionalProperties: false
      required:
      - outputSpace
      - outputs
      - promptHasDeniedWords
      - promptHasBlockedArtists
    types.Transform:
      type: object
      properties:
        azimuthAltitude:
          description: Transform is defined by azimuth, altitude and radius terms. If set, do not set `matrix` or `trs`.
          $ref: '#/components/schemas/types.AzimuthAltitude'
        matrix:
          description: Transform is defined as a matrix. If set, do not set `trs` or `azimuthAltitude`.
          type: array
          items:
            format: double
            type: number
          maxItems: 16
          minItems: 16
        trs:
          description: Transform is defined by translation, rotation and scale terms. If set, do not set `matrix` or `azimuthAltitude`.
          $ref: '#/components/schemas/types.TRS'
      additionalProperties: false
    restv1beta.ComposeOutput:
      type: object
      properties:
        backgroundImage:
          $ref: '#/components/schemas/restv1beta.ComposeOutputImage'
        image:
          $ref: '#/components/schemas/restv1beta.ComposeOutputImage'
        lightingSeed:
          type: integer
          format: int64
        maskImage:
          $ref: '#/components/schemas/restv1beta.ComposeOutputImage'
        seed:
          type: integer
          format: int64
      additionalProperties: false
      required:
      - seed
      - lightingSeed
      - image
      - backgroundImage
      - maskImage
    restv1beta.ComposeOutputImage:
      type: object
      properties:
        url:
          type: string
      additionalProperties: false
      required:
      - url
    rest_base.SourceURL:
      type: object
      properties:
        filename:
          description: Filename override. If unset, the service will try to detect the filename from the content disposition header, then the URL itself.
          type: string
        url:
          description: URL to fetch content from.
          type: string
          examples:
          - https://cdn.substance3d.com/v2/files/public/stepladder.usdz
      additionalProperties: false
      required:
      - url
    types.SceneCamera:
      type: object
      properties:
        focal:
          description: Camera focal length, in mm.
          type: number
          format: double
          default: 50
          maximum: 1000
          minimum: 10
        sensorWidth:
          description: Camera sensor width, in mm.
          type: number
          format: double
          default: 36
          maximum: 100
          minimum: 1
        transform:
          description: Controls the position and angle of the camera.
          $ref: '#/components/schemas/types.Transform'
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      description: 'Adobe service-to-service (S2S) access token. Pass `Authorization: Bearer <Token>`. The token is not a JWT.'
      scheme: bearer
      type: http
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Your client ID, which acts as the API key. Pass `x-api-key: <API_KEY>` using `<API_KEY>` as the placeholder in examples.'