Flux 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
servers:
- url: https://api.bfl.ai/v1
  description: Black Forest Labs Flux API
security:
- apiKeyAuth: []
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.
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'
components:
  schemas:
    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.
    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
    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.
    ErrorResponse:
      type: object
      description: Error response.
      properties:
        detail:
          type: string
          description: Human-readable error message.
        status_code:
          type: integer
          description: HTTP status code.
  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.
externalDocs:
  description: Flux Kontext Image Editing Documentation
  url: https://docs.bfl.ml/kontext/kontext_image_editing