Flux Image Editing API

openapi: 3.1.0
info:
  title: Flux Image Editing API
  description: >-
    REST API for editing and transforming existing images using Black Forest
    Labs' FLUX.1 Kontext models. The Kontext models accept an input image and
    a text prompt describing desired edits, returning a modified image. They
    support context-aware in-painting, object replacement, style transfer,
    background changes, and image-to-image transformations while preserving
    important visual context. Authentication requires an API key in the X-Key
    header. Requests are asynchronous and require polling for results.
  version: 'v1'
  contact:
    name: Black Forest Labs Support
    url: https://docs.bfl.ai/
  termsOfService: https://bfl.ai/legal/flux-api-service-terms
externalDocs:
  description: Flux Kontext Image Editing Documentation
  url: https://docs.bfl.ml/kontext/kontext_image_editing
servers:
  - url: https://api.bfl.ai/v1
    description: Black Forest Labs Flux API
tags:
  - name: Editing
    description: >-
      Endpoints for submitting image editing requests using FLUX.1 Kontext
      models. Accepts an input image and a text instruction to produce
      a transformed output image.
  - name: Results
    description: >-
      Endpoints for polling the status and retrieving completed image
      editing results.
security:
  - apiKeyAuth: []
paths:
  /flux-kontext-pro:
    post:
      operationId: editImageKontextPro
      summary: Edit image with FLUX.1 Kontext [pro]
      description: >-
        Submits an asynchronous image editing request using the FLUX.1
        Kontext [pro] model. Accepts a base64-encoded input image and a
        text prompt describing the desired edit. The model uses contextual
        understanding to apply targeted edits while preserving the rest of
        the image. Returns a task ID for polling. Use cases include object
        replacement, background changes, style application, and detailed
        touch-ups.
      tags:
        - Editing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KontextEditRequest'
      responses:
        '200':
          description: Editing task accepted. Poll the returned ID for results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          description: Bad request. Invalid parameters or image data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized. Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
  /flux-kontext-max:
    post:
      operationId: editImageKontextMax
      summary: Edit image with FLUX.1 Kontext [max]
      description: >-
        Submits an asynchronous image editing request using the FLUX.1
        Kontext [max] model, which offers maximum quality for image editing
        with enhanced prompt following and detail preservation. Accepts a
        base64-encoded input image and a text editing instruction. Returns
        a task ID for polling the result.
      tags:
        - Editing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KontextEditRequest'
      responses:
        '200':
          description: Editing task accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
  /get_result:
    get:
      operationId: getEditResult
      summary: Flux Poll for editing result
      description: >-
        Polls the status of an asynchronous image editing task. Returns the
        current status (Pending, Processing, Ready, Error, or Content
        Moderated). When status is Ready, the result object contains a
        pre-signed sample URL to download the edited image.
      tags:
        - Results
      parameters:
        - $ref: '#/components/parameters/taskIdParam'
      responses:
        '200':
          description: Task status and result (if ready).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Task not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Key
      description: >-
        API key from the Black Forest Labs developer portal. Pass in the
        X-Key header for all authenticated requests.
  parameters:
    taskIdParam:
      name: id
      in: query
      required: true
      description: The task ID returned by an editing request.
      schema:
        type: string
        format: uuid
  schemas:
    KontextEditRequest:
      type: object
      description: >-
        Request body for FLUX.1 Kontext image editing. Requires both an
        input image (base64-encoded) and a text prompt describing the desired
        edit to apply.
      required:
        - prompt
        - image
      properties:
        prompt:
          type: string
          description: >-
            Text instruction describing the desired edit. For best results,
            be specific about what to change and what to preserve (e.g.,
            "Change the car color to red, keep the background and surroundings
            unchanged").
          maxLength: 10000
        image:
          type: string
          description: >-
            The input image to edit, encoded as a base64 string. Supported
            formats are JPEG and PNG. The image should be provided without
            a data URI prefix.
          contentEncoding: base64
          contentMediaType: image/jpeg
        steps:
          type: integer
          description: Number of diffusion inference steps.
          minimum: 1
          maximum: 50
          default: 28
        guidance:
          type: number
          description: Guidance scale controlling prompt adherence strength.
          minimum: 1.5
          maximum: 10.0
          default: 3.5
        seed:
          type: integer
          description: Random seed for reproducible results.
          minimum: 0
        safety_tolerance:
          type: integer
          description: Content safety filter tolerance from 0 (strictest) to 6 (least strict).
          minimum: 0
          maximum: 6
          default: 2
        output_format:
          type: string
          description: Output image format for the edited result.
          enum:
            - jpeg
            - png
          default: jpeg
        prompt_upsampling:
          type: boolean
          description: >-
            If true, automatically enhances the editing prompt using an LLM
            before processing for improved edit quality.
          default: false
    TaskResponse:
      type: object
      description: >-
        Response returned when an image editing task is accepted. Contains
        the task ID for polling.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the editing task.
        polling_url:
          type: string
          format: uri
          description: Convenience URL for polling the task status.
    ResultResponse:
      type: object
      description: >-
        Response from the result polling endpoint. When status is Ready,
        the result contains a URL to download the edited image.
      properties:
        id:
          type: string
          format: uuid
          description: The task ID.
        status:
          type: string
          description: Current status of the editing task.
          enum:
            - Pending
            - Processing
            - Ready
            - Error
            - Content Moderated
            - Request Moderated
        result:
          type: object
          description: Result data, present only when status is Ready.
          properties:
            sample:
              type: string
              format: uri
              description: Pre-signed URL to download the edited image.
            prompt:
              type: string
              description: The prompt used for the edit.
            seed:
              type: integer
              description: The seed used for generation.
    ErrorResponse:
      type: object
      description: Error response.
      properties:
        detail:
          type: string
          description: Human-readable error message.
        status_code:
          type: integer
          description: HTTP status code.
    ValidationErrorResponse:
      type: object
      description: Validation error response when the request body fails validation.
      properties:
        detail:
          type: array
          description: List of validation errors.
          items:
            type: object
            properties:
              loc:
                type: array
                description: Location of the error in the request.
                items:
                  oneOf:
                    - type: string
                    - type: integer
              msg:
                type: string
                description: Error message.
              type:
                type: string
                description: Error type.