openapi: 3.1.0
info:
  title: Adobe Creative Suite Adobe Firefly API
  description: >-
    The Adobe Firefly API provides access to Adobe's generative AI capabilities for
    creating and editing images, vectors, and video from natural language prompts. Built
    on Adobe's Firefly family of creative generative models, which are trained on licensed
    and public domain content. Supports text-to-image generation, generative fill,
    generative expand, generating similar images, object compositing, and video generation.
    All generation operations are asynchronous.
  version: 3.0.0
  termsOfService: https://www.adobe.com/legal/terms.html
  contact:
    name: Adobe Developer Support
    url: https://developer.adobe.com/support/
  license:
    name: Adobe Developer Terms
    url: https://www.adobe.com/legal/developer-terms.html
servers:
- url: https://firefly-api.adobe.io/v3
  description: Adobe Firefly API v3 production server
security:
- bearerAuth: []
tags:
- name: Generative Expand
  description: Expand images beyond their original boundaries
- name: Generative Fill
  description: Fill selected regions of images with AI-generated content
- name: Image Generation
  description: Text-to-image and image variation generation operations
- name: Object Composite
  description: Composite AI-generated objects into existing images
- name: Status
  description: Asynchronous job status polling
- name: Video Generation
  description: Generate video from text prompts
paths:
  /images/generate-async:
    post:
      operationId: generateImagesAsync
      summary: Adobe Creative Suite Generate Images from Text Prompt
      description: >-
        Generates one or more images from a text prompt using the Adobe Firefly generative
        AI model. Supports optional style presets, content class selection, negative
        prompts, and seed values for reproducibility. The operation is asynchronous;
        use the returned job ID to poll for completion and retrieve output image URLs.
      tags:
      - Image Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerateRequest'
      responses:
        '202':
          description: Generation job accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobSubmitted'
        '400':
          description: Bad request - invalid prompt or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /images/expand-async:
    post:
      operationId: expandImageAsync
      summary: Adobe Creative Suite Generative Expand Image
      description: >-
        Expands an existing image beyond its original boundaries using generative AI
        to fill in the new regions. The expansion can be directional and supports
        specifying a prompt to guide the content generated in the expanded areas.
      tags:
      - Generative Expand
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageExpandRequest'
      responses:
        '202':
          description: Expand job accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /images/fill-async:
    post:
      operationId: fillImageAsync
      summary: Adobe Creative Suite Generative Fill
      description: >-
        Fills a masked region of an existing image with AI-generated content based on
        a text prompt. A mask image defines the area to be filled. The generative fill
        respects the surrounding context to produce seamlessly blended results.
      tags:
      - Generative Fill
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageFillRequest'
      responses:
        '202':
          description: Fill job accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /images/generate-similar-async:
    post:
      operationId: generateSimilarImagesAsync
      summary: Adobe Creative Suite Generate Similar Images
      description: >-
        Generates images that are visually similar to a provided reference image while
        optionally being guided by a text prompt. Useful for producing variations of an
        existing image or exploring stylistic alternatives based on a visual reference.
      tags:
      - Image Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateSimilarRequest'
      responses:
        '202':
          description: Generate similar job accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /images/generate-object-composite-async:
    post:
      operationId: generateObjectCompositeAsync
      summary: Adobe Creative Suite Generate Object Composite
      description: >-
        Generates an AI-rendered object and composites it into an existing scene image.
        The object is described via a text prompt and is placed into the scene with
        appropriate lighting, shadows, and perspective to appear naturally integrated.
      tags:
      - Object Composite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectCompositeRequest'
      responses:
        '202':
          description: Object composite job accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /videos/generate-async:
    post:
      operationId: generateVideoAsync
      summary: Adobe Creative Suite Generate Video from Text Prompt
      description: >-
        Generates a short video clip from a text prompt using the Adobe Firefly video
        generation model. Generally Available as of June 2025. Supports specifying
        duration, aspect ratio, and motion style through the request parameters. The
        operation is asynchronous and may take several minutes to complete.
      tags:
      - Video Generation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerateRequest'
      responses:
        '202':
          description: Video generation job accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncJobSubmitted'
        '400':
          description: Bad request - invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /status/{jobId}:
    get:
      operationId: getGenerationStatus
      summary: Adobe Creative Suite Get Async Job Status
      description: >-
        Retrieves the current status of an asynchronous Firefly generation job. Poll
        this endpoint after submitting a generation request to determine if the job
        is pending, running, succeeded, or failed. On success, the response includes
        URLs to the generated output images or video.
      tags:
      - Status
      parameters:
      - name: jobId
        in: path
        required: true
        description: Unique identifier of the generation job to check
        schema:
          type: string
          example: urn:firefly:jobs:abc123def456
        example: urn:firefly:jobs:abc123def456
      responses:
        '200':
          description: Job status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationStatus'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 access token obtained from Adobe IMS
  schemas:
    ImageGenerateRequest:
      type: object
      description: Request body for text-to-image generation
      required:
      - prompt
      properties:
        prompt:
          type: string
          description: Text description of the image to generate
          maxLength: 1024
          example: A serene mountain lake at golden hour with reflections of pine trees
        negativePrompt:
          type: string
          description: Text description of elements to avoid in the generated image
          maxLength: 1024
          example: blurry, low quality, distorted
        contentClass:
          type: string
          description: Broad content category to guide the generation model
          enum:
          - photo
          - art
          example: photo
        numVariations:
          type: integer
          description: Number of image variations to generate (1 to 4)
          minimum: 1
          maximum: 4
          default: 1
          example: 2
        size:
          $ref: '#/components/schemas/ImageSize'
        style:
          $ref: '#/components/schemas/StyleOptions'
        seeds:
          type: array
          description: >-
            Array of integer seed values for reproducible generation. Providing the
            same seed with the same prompt produces the same output.
          items:
            type: integer
          example:
          - 42
          - 1337
        locale:
          type: string
          description: BCP 47 language locale for prompt interpretation
          example: en-US
    ImageExpandRequest:
      type: object
      description: Request body for generative image expansion
      required:
      - image
      properties:
        prompt:
          type: string
          description: Text prompt to guide what content fills the expanded areas
          maxLength: 1024
          example: example_value
        negativePrompt:
          type: string
          description: Text describing what to avoid in the expanded areas
          maxLength: 1024
          example: example_value
        image:
          $ref: '#/components/schemas/InputImageReference'
        size:
          $ref: '#/components/schemas/ImageSize'
        placement:
          type: object
          description: Placement and inset parameters for the source image within the expanded canvas
          properties:
            inset:
              type: object
              properties:
                left:
                  type: integer
                top:
                  type: integer
                right:
                  type: integer
                bottom:
                  type: integer
        numVariations:
          type: integer
          minimum: 1
          maximum: 4
          default: 1
          example: 1920
        seeds:
          type: array
          items:
            type: integer
    ImageFillRequest:
      type: object
      description: Request body for generative fill operation
      required:
      - image
      - mask
      properties:
        prompt:
          type: string
          description: Text prompt describing what to fill in the masked area
          maxLength: 1024
          example: example_value
        negativePrompt:
          type: string
          description: Text describing what to avoid in the filled area
          maxLength: 1024
          example: example_value
        image:
          $ref: '#/components/schemas/InputImageReference'
        mask:
          $ref: '#/components/schemas/InputImageReference'
        numVariations:
          type: integer
          minimum: 1
          maximum: 4
          default: 1
          example: 1920
        seeds:
          type: array
          items:
            type: integer
    GenerateSimilarRequest:
      type: object
      description: Request body for generating images similar to a reference image
      required:
      - image
      properties:
        prompt:
          type: string
          description: Optional text prompt to further guide the style or content
          maxLength: 1024
          example: example_value
        image:
          $ref: '#/components/schemas/InputImageReference'
        numVariations:
          type: integer
          minimum: 1
          maximum: 4
          default: 1
          example: 1920
        size:
          $ref: '#/components/schemas/ImageSize'
        seeds:
          type: array
          items:
            type: integer
    ObjectCompositeRequest:
      type: object
      description: Request body for generating an object composite in a scene
      required:
      - prompt
      - image
      - mask
      properties:
        prompt:
          type: string
          description: Text description of the object to generate and composite
          maxLength: 1024
          example: example_value
        negativePrompt:
          type: string
          description: Text describing what to avoid in the generated object
          maxLength: 1024
          example: example_value
        contentClass:
          type: string
          enum:
          - photo
          - art
          example: photo
        image:
          $ref: '#/components/schemas/InputImageReference'
        mask:
          $ref: '#/components/schemas/InputImageReference'
        numVariations:
          type: integer
          minimum: 1
          maximum: 4
          default: 1
          example: 1920
        seeds:
          type: array
          items:
            type: integer
    VideoGenerateRequest:
      type: object
      description: Request body for text-to-video generation
      required:
      - prompt
      properties:
        prompt:
          type: string
          description: Text description of the video to generate
          maxLength: 1024
          example: A slow camera pan over a misty forest at dawn
        negativePrompt:
          type: string
          description: Text describing what to avoid in the generated video
          maxLength: 1024
          example: example_value
        size:
          type: object
          description: Output video dimensions
          properties:
            width:
              type: integer
              example: 1920
            height:
              type: integer
              example: 1080
        duration:
          type: number
          description: Requested video duration in seconds
          example: 5.0
    AsyncJobSubmitted:
      type: object
      description: Response returned immediately after an async generation job is submitted
      properties:
        jobId:
          type: string
          description: Unique identifier for the generation job
          example: urn:firefly:jobs:abc123def456
        statusUrl:
          type: string
          description: URL to poll for job status updates
          example: https://firefly-api.adobe.io/v3/status/urn:firefly:jobs:abc123def456
    GenerationStatus:
      type: object
      description: Current status and results of a Firefly generation job
      properties:
        jobId:
          type: string
          description: Unique identifier of the generation job
          example: urn:firefly:jobs:abc123def456
        status:
          type: string
          description: Current status of the generation job
          enum:
          - pending
          - running
          - succeeded
          - failed
          example: succeeded
        created:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the job was created
          example: example_value
        modified:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the job was last modified
          example: example_value
        outputs:
          type: array
          description: Generated output images or videos (present on success)
          items:
            $ref: '#/components/schemas/OutputImage'
        errors:
          type: array
          description: Errors encountered during generation (present on failure)
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
    OutputImage:
      type: object
      description: A single generated image output from a Firefly generation job
      properties:
        image:
          type: object
          description: Generated image reference
          properties:
            url:
              type: string
              description: Temporary signed URL to download the generated image
              example: https://firefly-api-prod-origin.adobe.io/v2/assets/urn:firefly:image:abc123
        seed:
          type: integer
          description: Seed value used to produce this particular output
          example: 42
        contentClass:
          type: string
          description: Content class detected or applied during generation
          enum:
          - photo
          - art
          example: photo
    InputImageReference:
      type: object
      description: Reference to an input image for generative operations
      required:
      - source
      properties:
        source:
          type: object
          description: Source of the input image
          properties:
            url:
              type: string
              description: Publicly accessible URL of the input image
              example: https://my-bucket.s3.amazonaws.com/source-image.jpg
            uploadId:
              type: string
              description: Upload ID for a previously uploaded image via the Firefly upload API
    ImageSize:
      type: object
      description: Dimensions for the output image
      properties:
        width:
          type: integer
          description: Output image width in pixels
          example: 1024
        height:
          type: integer
          description: Output image height in pixels
          example: 1024
    StyleOptions:
      type: object
      description: Style guidance for image generation
      properties:
        presets:
          type: array
          description: List of style preset identifiers to apply
          items:
            type: string
            enum:
            - photo
            - art
            - graphic
            - bw
            - cool_colors
            - warm_tone
            - muted_color
            - vibrant_color
            - pastel_color
            - golden_hour
            - closeup_portrait
            - wide_angle
            - aerial_view
            - landscape_photography
          example:
          - photo
          - golden_hour
        strength:
          type: integer
          description: Style influence strength from 1 (subtle) to 100 (strong)
          minimum: 1
          maximum: 100
          example: 60
        referenceImage:
          $ref: '#/components/schemas/InputImageReference'
    StylePreset:
      type: string
      description: Available style preset identifiers for Firefly generation
      enum:
      - photo
      - art
      - graphic
      - bw
      - cool_colors
      - warm_tone
      - muted_color
      - vibrant_color
      - pastel_color
      - golden_hour
    ErrorResponse:
      type: object
      description: Standard error response body
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: example_value
        message:
          type: string
          description: Human-readable description of the error
          example: example_value
        requestId:
          type: string
          description: Unique identifier for the failed request, for support purposes
          example: asset_abc123