Adobe Suite Common Operations API

openapi: 3.2.0
info:
  version: 3.0.0
  title: Firefly Common 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: Common Operations
  description: Core Firefly API operations for generating and manipulating images and videos.
paths:
  /v3/images/generate-async:
    post:
      operationId: generateImagesV3Async
      summary: Generate images
      description: Generate images based on a text prompt. You may also include a reference image and Firefly will try to mimic the characteristics, such as color scheme, lighting, layout of objects in the image, etc.
      tags:
      - Common Operations
      parameters:
      - name: x-model-version
        in: header
        description: Specify the Firefly model version to use for the image generation. When a custom model is used, a `customModelId` must also be passed in the request body.
        required: false
        schema:
          type: string
          default: image3
          enum:
          - image3
          - image3_custom
          - image4_standard
          - image4_ultra
          - image4_custom
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateImagesRequestV3'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_generateImagesV3Async'
        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
        '413':
          content:
            text/html:
              schema:
                type: string
          description: Request Entity Too Large
        '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
                unsupported_value:
                  summary: Unsupported value
                  value:
                    error_code: validation_error
                    validation_errors:
                    - loc:
                      - body
                      - seeds
                      msg: ensure this value has at most 1 items
                      type: value_error.list.max_items
                assertion_violation:
                  summary: Assertion violation
                  value:
                    error_code: cai_assertion_violation_error
                    message: Request failed content assertion checks.
              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
  /v4/images/generate-async:
    post:
      operationId: firefly_image_v5_generate_async_v4
      summary: Generate images with Image5
      description: Generate images asynchronously using Firefly's Image5 model. When <code>referenceBlobs</code> is included in the request, omit <code>aspectRatio</code> or set it to <code>auto</code>.
      tags:
      - Common Operations
      parameters:
      - name: x-model-version
        in: header
        required: true
        schema:
          type: string
          enum:
          - image5
          default: image5
        description: The model version to use for image generation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerateRequestV3'
            examples:
              fullPayload:
                summary: Full payload example
                value:
                  prompt: A futuristic city glowing at night, with neon lights and flying cars
                  aspectRatio: auto
                  resolutionLevel: 2.4MP
                  modelId: firefly_image
                  numVariations: 1
                  seeds:
                  - 42345
                  modelSpecificPayload:
                    localeCode: en-US
                    prompt_reasoner: quality
                  referenceBlobs:
                  - source:
                      url: https://example.com/reference-image.jpg
                    usage: general
              textToImageGeneration:
                summary: Text-to-Image generation
                value:
                  prompt: A hyper-detailed illustration of a floating city at sunrise
                  aspectRatio: '16:9'
                  resolutionLevel: 4MP
                  modelId: firefly_image
                  numVariations: 1
                  referenceBlobs: []
              imageToImageInstructEdit:
                summary: Image-to-Image instruct edit
                value:
                  prompt: Add warm sunset lighting and enhance the reflection on the water
                  resolutionLevel: 2.4MP
                  modelId: firefly_image
                  numVariations: 1
                  referenceBlobs:
                  - source:
                      uploadId: 123e4567-e89b-12d3-a456-426614174000
                    usage: general
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncTaskResponse'
              example:
                links:
                  cancel:
                    href: https://firefly-api.adobe.io/v3/cancel/job-abc123
                  result:
                    href: https://firefly-api.adobe.io/v3/status/job-abc123
                progress: 0
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Requested Resource Was Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '408':
          description: Request Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              examples:
                invalid_enum:
                  summary: Invalid enum value
                  value:
                    error_code: validation_error
                    validation_errors:
                    - loc:
                      - body
                      - aspectRatio
                      msg: 'value is not a valid enumeration member; permitted: ''1:1'', ''4:3'', ''3:4'', ''16:9'', ''9:16'', ''auto'''
                      type: type_error.enum
                unsupported_value:
                  summary: Unsupported value
                  value:
                    error_code: validation_error
                    validation_errors:
                    - loc:
                      - body
                      - numVariations
                      msg: ensure this value is less than or equal to 1
                      type: value_error.number.not_le
                assertion_violation:
                  summary: Assertion violation
                  value:
                    error_code: cai_assertion_violation_error
                    message: Request failed content assertion checks.
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '451':
          description: Unavailable For Legal Reasons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentPolicyErrorResponse'
              examples:
                prompt_unsafe:
                  summary: Unsafe prompt
                  value:
                    error_code: prompt_unsafe
                    message: The prompt did not pass content policy checks.
                input_image_unsafe:
                  summary: Unsafe input image
                  value:
                    error_code: input_media_unsafe
                    message: The input image did not pass content policy checks.
        '499':
          description: Client Closed Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v3/images/generate-similar-async:
    post:
      operationId: generateSimilarImagesV3Async
      summary: Generate similar images
      description: Generate similar images based on a reference image that you provide as a parameter.
      tags:
      - Common Operations
      parameters:
      - name: x-model-version
        in: header
        description: Specify the Firefly model version to use for the image generation.
        required: false
        schema:
          type: string
          default: image3
          enum:
          - image3
          - image4_standard
          - image4_ultra
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateSimilarImagesRequestV3'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_generateSimilarImagesV3Async'
        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
        '413':
          content:
            text/html:
              schema:
                type: string
          description: Request Entity Too Large
        '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/expand-async:
    post:
      operationId: expandImagesV3Async
      summary: Expand image
      description: Change the aspect ratio or size of an image to expand it. Optionally, provide a text prompt to generate additional imagery for the expansion.
      tags:
      - Common Operations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpandImageRequestV3'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_expandImagesV3Async'
        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
        '413':
          content:
            text/html:
              schema:
                type: string
          description: Request Entity Too Large
        '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/fill-async:
    post:
      operationId: fillImagesV3Async
      summary: Fill image
      description: Generates a fill in an area of an image based on a text prompt. A mask defines the area of the image to be filled.
      tags:
      - Common Operations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FillImageRequestV3'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_fillImagesV3Async'
        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
        '413':
          content:
            text/html:
              schema:
                type: string
          description: Request Entity Too Large
        '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/videos/generate:
    post:
      operationId: generateVideoV3
      summary: Generate video
      description: Generate a five second video using a text prompt.
      tags:
      - Common Operations
      parameters:
      - name: x-model-version
        in: header
        description: Specify the Firefly model version to use for the video generation.
        required: true
        schema:
          type: string
          enum:
          - video1_standard
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateVideoRequestV3'
        required: true
        description: The request body for the video generation.
      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:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Bad Request
        '403':
          content:
            application/json:
              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:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Request Timeout
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unsupported Media Type
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              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:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Internal Server Error
  /v3/custom-models:
    get:
      summary: Retrieve custom models
      description: Retrieve the custom models for a user.
      operationId: getCustomModels
      tags:
      - Common Operations
      parameters:
      - name: x-user-token
        in: header
        description: A user token referencing the user's individual account, obtained using their credentials. The user token must be preceded by `Bearer`.
        schema:
          type: string
      - name: x-request-id
        in: header
        description: A unique request identifier defined by you. This is used by Adobe Support to trace the request in logs. This header is automatically generated by the server if not explicitly set.
        required: true
        schema:
          type: string
      - name: sortBy
        in: query
        description: A sorting option for the response list. For a reverse sort, use `-` (e.g., `-modifiedDate`). Multi-vector sorting is not currently supported.
        schema:
          type: string
          default: modifiedDate
          enum:
          - assetName
          - createdDate
          - modifiedDate
      - name: start
        in: query
        description: The first result to include in a paginated response. Required if a `limit` is specified.
        schema:
          type: string
          default: '0'
      - name: limit
        in: query
        description: The number of custom models to return in a paginated response.
        schema:
          type: string
          maximum: 50
          minimum: 1
      - name: publishedState
        in: query
        des

# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adobe-suite/refs/heads/main/openapi/adobe-suite-common-operations-api-openapi.yml