openapi: 3.2.0
info:
  version: 3.0.0
  title: Firefly Composite Operations API
  description: REST API for Adobe Firefly services including image generation, image alteration, image upscaling, video generation, and other related services.
servers:
- url: https://firefly-api.adobe.io
  description: Production server.
security:
- X-Api-Key: []
  AccessToken: []
tags:
- name: Composite Operations
  description: 'Object composite image generation: prompt-based composite, precise composite, and adaptive composite endpoints.'
paths:
  /v3/images/generate-object-composite-async:
    post:
      operationId: generateObjectCompositeV3Async
      summary: Generate object composite
      description: 'Combines your image and images generated by Firefly to create an image composite, or scene. The images that Firefly generates are based on a text prompt that you provide. You can upload an image with or without an image mask, such as a product photo, but for a successful result one of the following conditions must be true: <ul> <li>The request size is larger than the input image, OR</li> <li>The image contains a transparent layer/channel, OR</li> <li>A mask is provided</li> </ul>'
      tags:
      - Composite Operations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateObjectCompositeRequestV3'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_generateObjectCompositeV3Async'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncAcceptResponseV3'
          description: Accepted
          headers:
            Link:
              description: Links to check the job status or cancel the job.
              schema:
                type: string
        '400':
          content:
            application/json:
              examples:
                bad_request:
                  value:
                    error_code: bad_request
                empty_input_body:
                  value:
                    error_code: empty_input_body
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Bad Request
        '403':
          content:
            application/json:
              examples:
                access_error:
                  value:
                    error_code: access_error
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Forbidden
          headers:
            x-access-error:
              description: Indicates the reason access is not authorized.
              schema:
                type: string
                enum:
                - quota_exhausted
                - user_non_entitled
                - user_profile_denied
                - invalid_ims_scope
        '408':
          content:
            application/json:
              examples:
                timeout_error:
                  value:
                    error_code: timeout_error
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Request Timeout
        '415':
          content:
            application/json:
              examples:
                invalid_content_type:
                  value:
                    error_code: invalid_content_type
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unsupported Media Type
        '422':
          content:
            application/json:
              examples:
                validation_error:
                  value:
                    error_code: validation_error
                    validation_errors:
                    - ctx:
                        enum_values:
                        - photo
                        - art
                      loc:
                      - body
                      - contentClass
                      msg: 'value is not a valid enumeration member; permitted: ''photo'', ''art'''
                      type: type_error.enum
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              examples:
                rate_limited:
                  value:
                    error_code: rate_limited
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Too Many Requests
          headers:
            retry-after:
              description: Indicates the date after which the client should retry the request.
              schema:
                type: string
            x-access-rate-limit-level:
              description: 'Indicates the level at which the rate limit was applied. Possible values are:

                - org: The rate limit was applied to the organization

                - account: The rate limit was applied to the organization''s tech account.'
              schema:
                type: string
        '500':
          content:
            application/json:
              examples:
                runtime_error:
                  value:
                    error_code: runtime_error
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Internal Server Error
  /v3/images/precise-composite:
    post:
      operationId: preciseComposite
      summary: Generate precise composite
      description: Submits an asynchronous precise composite generation job using the precise composite pipeline.
      tags:
      - Composite Operations
      parameters:
      - name: content-type
        in: header
        required: true
        description: Must be application/json for JSON request body.
        schema:
          type: string
          enum:
          - application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreciseCompositeRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '451':
          description: Unavailable For Legal Reasons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentPolicyErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
  /v3/images/adaptive-composite:
    post:
      operationId: adaptiveComposite
      summary: Generate adaptive composite
      description: Submits an asynchronous adaptive composite generation job using the adaptive composite pipeline.
      tags:
      - Composite Operations
      parameters:
      - name: content-type
        in: header
        required: true
        description: Must be application/json for JSON request body.
        schema:
          type: string
          enum:
          - application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdaptiveCompositeRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '451':
          description: Unavailable For Legal Reasons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentPolicyErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorGeneric'
components:
  schemas:
    Placement:
      properties:
        alignment:
          allOf:
          - $ref: '#/components/schemas/PlacementAlignment'
          description: Specify horizontal and vertical alignment. Possible values for horizontal=(center|left|right) and for vertical=(center|top|bottom).
          title: Alignment
        inset:
          allOf:
          - $ref: '#/components/schemas/PlacementInset'
          description: Margin values in target size.
          title: Margin values in target size
      title: Placement
      type: object
    PublicBinaryInputV3:
      properties:
        uploadId:
          description: The `uploadId` from the storage API response.
          format: uuid4
          title: The upload ID
          type: string
        url:
          description: 'The pre-signed URL of an uploaded file. Use a URL or an `uploadID` as the source for the image. Firefly only allows these listed domains in the request: <ul> <li><code>amazonaws.com</code></li> <li><code>windows.net</code></li> <li><code>dropboxusercontent.com</code></li> <li><code>storage.googleapis.com</code></li> </ul>.'
          format: uri
          maxLength: 2083
          minLength: 1
          title: The pre-signed URL
          type: string
      title: PublicBinaryInputV3
      type: object
    Size:
      properties:
        height:
          maximum: 4096
          minimum: 1
          type: integer
        width:
          maximum: 4096
          minimum: 1
          type: integer
      required:
      - width
      - height
      type: object
    InputImageV3:
      properties:
        mask:
          allOf:
          - $ref: '#/components/schemas/PublicBinaryInputV3'
          deprecated: true
          description: This is a deprecated property. Use <code>mask</code> instead.
          title: Deprecated mask image
        source:
          $ref: '#/components/schemas/PublicBinaryInputV3'
          description: Source image that Firefly expands, fills, or uses to generate similar images.
      required:
      - source
      title: InputImageV3
      type: object
    AlignmentVertical:
      description: An enumeration.
      enum:
      - center
      - top
      - bottom
      title: AlignmentVertical
    ImageRef:
      type: object
      required:
      - source
      properties:
        source:
          $ref: '#/components/schemas/ImageSource'
    BackgroundInput:
      type: object
      required:
      - image
      - fillAreaMask
      properties:
        image:
          $ref: '#/components/schemas/ImageRef'
          description: Background image on which the object will be placed.
        fillAreaMask:
          $ref: '#/components/schemas/ImageRef'
          description: Mask defining where the object should be placed on the background.
    AsyncAcceptResponseV3:
      properties:
        cancelUrl:
          description: The URL to cancel the job.
          title: Cancel URL
          type: string
        jobId:
          description: The ID of the job.
          title: Job ID
          type: string
        statusUrl:
          description: The URL to check the status of the job.
          title: Status URL
          type: string
      required:
      - jobId
      - statusUrl
      - cancelUrl
      title: AsyncAcceptResponseV3
      type: object
    AdaptiveObjectInput:
      type: object
      required:
      - image
      properties:
        image:
          $ref: '#/components/schemas/ImageRef'
          description: Object image to be composited onto the background.
        mask:
          $ref: '#/components/schemas/ImageRef'
          description: Optional object mask.
    AdaptiveCompositeRequest:
      type: object
      required:
      - background
      - object
      properties:
        background:
          $ref: '#/components/schemas/BackgroundInput'
          description: Background image and fill area mask.
        object:
          $ref: '#/components/schemas/AdaptiveObjectInput'
          description: Object image and optional mask.
        numVariations:
          type: integer
          minimum: 1
          maximum: 3
          default: 1
          description: Number of output variations to generate.
        seeds:
          type: array
          items:
            type: integer
          minItems: 1
          maxItems: 3
          description: 'Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls. If specified alongside numVariations, the number of seeds must equal numVariations. Defaults: 1 variation → [333], 2 → [333, 222], 3 → [333, 222, 111].'
        harmonization:
          type: number
          format: float
          minimum: 0
          maximum: 1
          default: 0.6
          description: Controls how much the object's colors and lighting are adjusted to match the background scene.
        shadowIntensity:
          type: number
          format: float
          minimum: 0
          maximum: 1
          default: 1
          description: Controls shadow intensity in the composited result. Lower values reduce shadow.
        preserveBackground:
          type: boolean
          default: false
          description: When true, preserves original background details within the masked area during compositing.
        output:
          $ref: '#/components/schemas/OutputSpec'
          description: Output format specification.
    ValidationErrorResponse:
      type: object
      title: ValidationErrorResponse
      description: Error response body for HTTP 422 (validation failures).
      required:
      - error_code
      properties:
        error_code:
          $ref: '#/components/schemas/ValidationErrorCode422'
        message:
          type: string
          description: Human-readable error description.
        validation_errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
          description: List of field-level validation errors.
    ValidationErrorDetail:
      type: object
      properties:
        loc:
          type: array
          items:
            oneOf:
            - type: string
            - type: integer
          description: Path to the field that caused the error.
        msg:
          type: string
          description: Human-readable error message.
        type:
          type: string
          description: Error type identifier.
        ctx:
          type: object
          additionalProperties: true
          description: Additional context about the error.
    ApiErrorGeneric:
      type: object
      title: ApiErrorGeneric
      description: The error within the error response for non-400 failure responses.
      properties:
        error_code:
          type: string
          description: The error code.
        message:
          title: Message
          description: A human-readable error message.
          type: string
    ContentPolicyErrorCode451:
      type: string
      title: ContentPolicyErrorCode451
      description: Error code for HTTP 451 responses (content policy, legal, or safety).
      enum:
      - legal_error
      - prompt_unsafe
      - prompt_entity_denied
      - image_unsafe
      - video_unsafe
      - reference_image_unsafe_error
      - input_media_unsafe
    ObjectInput:
      type: object
      required:
      - image
      properties:
        image:
          $ref: '#/components/schemas/ImageRef'
          description: Object image to be composited onto the background.
    ImageSource:
      type: object
      properties:
        uploadId:
          type: string
          format: uuid
          description: If this object represents a file in our S3 temp storage system, the ID for that file.
        url:
          type: string
          format: uri
          description: Pre-signed URL of the image from a supported domain. [See Allowed storage domains](https://github.com/your-repo/your-project/blob/main/src/pages/getting-started/usage-notes/index.md#allowed-storage-domains) for the current list.
      description: The image source. Exactly one of `url` or `uploadId` must be provided in the request.
    Body_generateObjectCompositeV3Async:
      properties:
        files:
          items:
            format: binary
            type: string
          title: Files
          type: array
        request:
          $ref: '#/components/schemas/GenerateObjectCompositeRequestV3'
      required:
      - request
      - files
      title: Body_generateObjectCompositeV3Async
      type: object
    BaseInputMaskV3:
      properties:
        source:
          $ref: '#/components/schemas/PublicBinaryInputV3'
          description: Original mask image.
      title: BaseInputMaskV3
      type: object
    GenerateObjectCompositeRequestV3:
      properties:
        contentClass:
          $ref: '#/components/schemas/ContentClassV3'
        image:
          $ref: '#/components/schemas/InputImageV3'
          description: 'The image to expand. Use a URL or an <code>uploadID</code> as the source for the image. Firefly only allows these listed domains for input URLs in the request: <ul> <li><code>amazonaws.com</code></li> <li><code>windows.net</code></li> <li><code>dropboxusercontent.com</code></li> <li><code>storage.googleapis.com</code></li> </ul>.'
        mask:
          $ref: '#/components/schemas/BaseInputMaskV3'
          description: Selected areas of a background image that Firefly uses to fill the source image.
        numVariations:
          description: Generate this number of variations. Defaults to the number of seed images, or to 1 if you do not specify seeds.
          maximum: 4
          minimum: 1
          title: The number of variations to generate
          type: integer
        placement:
          $ref: '#/components/schemas/Placement'
          description: The position of the source image after Firefly adjusts it. The value describes the horizontal and vertical placement and dimensions of the image in the output. Note you cannot use placement for source images when you also apply a mask image.
        prompt:
          description: A text prompt up to 1024 characters. The longer the prompt the better Firefly performs.
          maxLength: 1024
          minLength: 1
          title: The prompt
          type: string
        seeds:
          description: 'Array of seed image IDs. These reference images help ensure consistent image generation across multiple API calls.


            If specified along with <code>numVariations</code>, the number of seeds must equal <code>numVariations</code>.'
          items:
            type: integer
          maxItems: 4
          minItems: 1
          title: The seed image for each variation
          type: array
          uniqueItems: true
        size:
          allOf:
          - $ref: '#/components/schemas/Size'
          default:
            height: 2048
            width: 2048
          description: 'The desired width and height for the final image in pixels. The supported sizes for the output images are: <ul> <li>Square (1:1) - width 2048px, height 2048px </li> <li>Square (1:1) - width 1024px, height 1024px </li> <li>Landscape (4:3)  - width 2304px, height 1792px </li> <li>Portrait (3:4)  - width 1792px, height 2304px</li> <li>Widescreen (16:9) - width 2688px, height 1536px </li> <li>(7:4)  - width 1344px, height 768px </li> <li>(9:7) - width 1152px, height 896px </li> <li>(7:9) - width 896px, height 1152px</li> </ul>.'
          title: The size
        style:
          $ref: '#/components/schemas/StylesV3'
      required:
      - image
      - prompt
      title: Generate object composite from prompt request
      type: object
    ValidationErrorCode422:
      type: string
      title: ValidationErrorCode422
      description: Error code for HTTP 422 responses (request validation only).
      enum:
      - validation_error
      - cai_assertion_violation_error
    ValidationErrorMessage:
      properties:
        ctx:
          title: Ctx
          type: object
        loc:
          items:
            anyOf:
            - type: integer
            - type: string
          title: Loc
          type: array
        msg:
          title: Msg
          type: string
        type:
          title: Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationErrorMessage
      type: object
    OutputSpec:
      type: object
      properties:
        mediaType:
          type: string
          enum:
          - image/png
          - image/jpeg
          - image/webp
          - image/jxl
          description: MIME type for the output image.
    ColligoErrorCodeAsyncV3:
      description: An enumeration.
      enum:
      - validation_error
      - runtime_error
      - timeout_error
      - rate_limited
      - access_error
      - invalid_content_type
      - empty_input_body
      - bad_request
      type: string
    PlacementAlignment:
      properties:
        horizontal:
          allOf:
          - $ref: '#/components/schemas/AlignmentHorizontal'
          default: center
        vertical:
          allOf:
          - $ref: '#/components/schemas/AlignmentVertical'
          default: center
      title: PlacementAlignment
      type: object
    PreciseCompositeRequest:
      type: object
      required:
      - background
      - object
      properties:
        background:
          $ref: '#/components/schemas/BackgroundInput'
          description: Background image and fill area mask specifying object placement.
        object:
          $ref: '#/components/schemas/ObjectInput'
          description: Object image to be placed on the background.
        numVariations:
          type: integer
          minimum: 1
          maximum: 3
          default: 1
          description: Number of output variations to generate.
        seeds:
          type: array
          items:
            type: integer
          minItems: 1
          maxItems: 3
          description: 'Random seeds for each variation. Count must match numVariations if both are provided. Defaults: 1 variation → [333], 2 → [333, 222], 3 → [333, 222, 111].'
        blend:
          type: number
          format: float
          minimum: 0
          maximum: 1
          default: 0.5
          description: Controls blend between harmonized and original object appearance (0.0 = fully harmonized, 1.0 = original preserved).
        output:
          $ref: '#/components/schemas/OutputSpec'
          description: Output format specification.
    StylesV3:
      properties:
        imageReference:
          $ref: '#/components/schemas/StylesImageReferenceV3'
        presets:
          description: The style presets. Specify an ID for a style of image to generate.
          items:
            type: string
          type: array
          uniqueItems: true
        strength:
          description: How strictly Firefly should adhere to the style you provide. 0 means no adherence. 100 means full adherence.
          exclusiveMinimum: 0
          maximum: 100
          type: integer
      type: object
    ContentClassV3:
      description: The content class of the image.
      enum:
      - photo
      - art
      type: string
    PlacementInset:
      properties:
        bottom:
          description: The space between bottom edge of the result image and bottom edge of the placed object image.
          title: Bottom Inset
          type: integer
        left:
          description: The space between left edge of the result image and left edge of the placed object image.
          title: Left Inset
          type: integer
        right:
          description: The space between right edge of the result image and right edge of the placed object image.
          title: Right Inset
          type: integer
        top:
          description: The space between top edge of the result image and top edge of the placed object image.
          title: Top Inset
          type: integer
      title: PlacementInset
      type: object
    AlignmentHorizontal:
      description: An enumeration.
      enum:
      - center
      - left
      - right
      title: AlignmentHorizontal
    AsyncJobResponse:
      type: object
      properties:
        status:
          type: string
          description: Current status of the job.
          example: running
        jobId:
          type: string
          description: Job URN identifier.
        statusUrl:
          type: string
          format: uri
          description: URL to poll for job status.
        cancelUrl:
          type: string
          format: uri
          description: URL to cancel the job.
    ContentPolicyErrorResponse:
      type: object
      title: ContentPolicyErrorResponse
      description: Error response body for HTTP 451 (content policy, legal, or safety).
      required:
      - error_code
      properties:
        error_code:
          $ref: '#/components/schemas/ContentPolicyErrorCode451'
        message:
          type: string
          description: Human-readable error description.
    ApiError:
      description: The error within the error response.
      properties:
        error_code:
          $ref: '#/components/schemas/ColligoErrorCodeAsyncV3'
        message:
          title: Message
          type: string
        stack_trace:
          items:
            type: string
          title: Stack Trace
          type: array
        validation_errors:
          items:
            $ref: '#/components/schemas/ValidationErrorMessage'
          title: Validation Errors
          type: array
      required:
      - error_code
      title: ApiError
      type: object
    StylesImageReferenceV3:
      properties:
        source:
          $ref: '#/components/schemas/PublicBinaryInputV3'
      type: object
  securitySchemes:
    AccessToken:
      type: http
      scheme: bearer
      description: The Adobe-generated access token, S2S format.
    X-Api-Key:
      type: apiKey
      name: x-api-key
      in: header
      description: The client ID for authentication.