Flux Kontext Image Generation

Generate and edit images using Flux Kontext model, supporting text-to-image and image editing

POST /v1/images/generations

cURL

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-kontext-pro",
    "prompt": "Cyberpunk city at night, neon lights flickering",
    "size": "16:9",
    "metadata": {
      "response_format": "png"
    }
  }'

200

{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "flux-kontext-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}

• Flux Kontext image generation and editing model
• Choose flux-kontext-pro (Pro) or flux-kontext-max (Max, higher quality) via the model parameter
• Supports text-to-image and image editing modes
• With reference image = image editing; without = text-to-image
• Fixed billing per request
• Async task mode, returns task_id for querying results

Important Change: For better performance and cost control, we no longer support passing base64 image data directly in image_urls. Please use the Upload Image API first to upload images and get URLs, then call this endpoint.

Authorization

Authorization · string · required

All endpoints require Bearer Token authentication

Get your API Key: Visit the API Key Management Page to get your API Key

Add to request header:

Authorization: Bearer YOUR_API_KEY

Request Parameters

model · string · required

Image generation model name

Options:

• flux-kontext-pro - Pro version
• flux-kontext-max - Max version, higher quality

prompt · string · required

Text description for image generation

size · string

Image aspect ratio

Default:

• With reference image: match_input_image (match input image)
• Without reference image: 16:9

Supported aspect ratios:

Value	Description
match_input_image	Match input image ratio (image editing only)
1:1	Square
4:3 / 3:4	Traditional display ratio
16:9 / 9:16	Widescreen/portrait
3:2 / 2:3	Standard photo
21:9 / 9:21	Ultrawide/ultra-narrow

image_urls · string[]

Reference image URL array for image editing

⚠️ URL format only (base64 not supported)

• Publicly accessible image URL (http:// or https://)
• Use the Upload Image API to upload local images and get URLs

Limits:

• Maximum 1 image
• With image = image editing mode; without = text-to-image mode

metadata · object

Metadata parameters for additional configuration options

Show Supported metadata fields

response_format · string · default: "png"

Output image format

Options: png, jpg

safety_tolerance · integer · default: 2

Safety filter tolerance

Range: 0 - 6, higher values = higher tolerance

prompt_upsampling · boolean · default: false

Enable prompt enhancement

• true: Auto-optimize/expand prompt
• false: Use original prompt (default)

Response

id · string

Unique task identifier for querying task status

object · string

Object type, fixed as generation.task

model · string

Model name used for generation

status · string

Task status

• queued - Waiting to be processed
• in_progress - Processing
• completed - Successfully completed
• failed - Failed

progress · integer

Task progress percentage (0-100)

created_at · integer

Task creation timestamp (Unix timestamp)

metadata · object

Task metadata

Use Cases

Case 1: Text-to-Image

{
  "model": "flux-kontext-pro",
  "prompt": "Cyberpunk city at night, neon lights flickering",
  "size": "16:9",
  "metadata": {
    "response_format": "png",
    "safety_tolerance": 2
  }
}

Case 2: Image Editing

{
  "model": "flux-kontext-max",
  "prompt": "Transform this photo into watercolor style",
  "size": "match_input_image",
  "image_urls": ["https://example.com/photo.jpg"],
  "metadata": {
    "response_format": "jpg",
    "prompt_upsampling": true
  }
}

Case 3: High-Quality Text-to-Image (Max Model)

{
  "model": "flux-kontext-max",
  "prompt": "A cute orange cat sunbathing on a windowsill, photorealistic style",
  "size": "1:1",
  "metadata": {
    "response_format": "png",
    "safety_tolerance": 3
  }
}

Query Task Results

Image generation is an async task. After submission, a task ID is returned. Use the Get Task Status endpoint to query generation progress and results.

cURL

curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-kontext-pro",
    "prompt": "Cyberpunk city at night, neon lights flickering",
    "size": "16:9",
    "metadata": {
      "response_format": "png"
    }
  }'

200

{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "flux-kontext-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}