Skip to main content
POST
/
api
/
v1
/
flux
/
kontext
/
generate
Generate or Edit Image
curl --request POST \
  --url https://api.kie.ai/api/v1/flux/kontext/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "A serene mountain landscape at sunset with a lake reflecting the orange sky",
  "enableTranslation": true,
  "aspectRatio": "16:9",
  "outputFormat": "jpeg",
  "promptUpsampling": false,
  "model": "flux-kontext-pro"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task12345"
  }
}

​
Usage Modes

  1. Text-to-Image Generation
    • Provide prompt and aspectRatio
    • Model will generate a new image based on the text description
  2. Image Editing
    • Provide prompt and inputImage
    • You can optionally provide an aspectRatio.
      • If supplied, the output will be cropped or padded to match this ratio.
      • If omitted, the original image’s ratio will be preserved.
    • Model will edit the input image according to the prompt

​
Important Notes

  • Generated images will expire after 14 days
  • Prompts only support English
  • Choose the appropriate model based on your needs:
    • flux-kontext-pro: Standard model for most use cases
    • flux-kontext-max: Enhanced model for complex scenes

Authorizations

​
Authorization
string
header
required

All APIs require authentication via Bearer Token.

Get API Key:

  1. Visit API Key Management Page to get your API Key

Usage: Add to request header: Authorization: Bearer YOUR_API_KEY

Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately in the management page

Body

application/json
​
prompt
string
required

Text prompt describing the desired image or edit. Required for both generation and editing modes.

  • Should be detailed and specific
  • For image editing, describe the desired changes
  • For image generation, describe the complete scene
  • IMPORTANT: Only English language is supported
Example:

"A serene mountain landscape at sunset with a lake reflecting the orange sky"

​
enableTranslation
boolean

Whether to enable automatic translation feature.

  • Since prompt only supports English, when this parameter is true, the system will automatically translate non-English prompts to English
  • If your prompt is already in English, you can set this to false
  • Default value: true
Example:

true

​
uploadCn
boolean

(Optional) Specifies the server region for image upload. Set to true to use servers in China, false to use non-China servers. Choose based on your geographical location for optimal upload speeds.

Example:

false

​
inputImage
string<uri>

URL of the input image for editing mode. Required when editing an existing image.

  • Must be a valid image URL
  • Image must be accessible to the API server
Example:

"https://example.com/input-image.jpg"

​
aspectRatio
enum<string>
default:16:9

Output image aspect ratio. You Applicable in both text-to-image generation and image editing modes.

For text-to-image generation , the output image will follow the specified aspect ratio.

For image editing , if aspectRatio is provided, the edited image will follow that ratio. If not provided, the image will retain its original aspect ratio.

Supported Aspect Ratios:

RatioFormat TypeCommon Use Cases
21:9Ultra-wideCinematic displays, panoramic views
16:9WidescreenHD video, desktop wallpapers
4:3StandardTraditional displays, presentations
1:1SquareSocial media posts, profile pictures
3:4PortraitMagazine layouts, portrait photos
9:16Mobile PortraitSmartphone wallpapers, stories

Note: Default ratio is "16:9" if not specified.

Available options:
21:9,
16:9,
4:3,
1:1,
3:4,
9:16
​
outputFormat
enum<string>
default:jpeg

Output image format.

Available options:
jpeg,
png
​
promptUpsampling
boolean
default:false
  • If true, performs upsampling on the prompt
  • May increase processing time
​
model
enum<string>
default:flux-kontext-pro

Model version to use for generation.

Available Options:

ModelDescription
flux-kontext-proStandard model with balanced performance
flux-kontext-maxEnhanced model with advanced capabilities

Note: Choose flux-kontext-max for more demanding tasks that require higher quality and detail

Available options:
flux-kontext-pro,
flux-kontext-max
​
callBackUrl
string<uri>

The URL to receive image generation or editing task completion updates. Optional but recommended for production use.

  • System will POST task status and results to this URL when image generation or editing completes
  • Callback includes generated image URLs and task information for both text-to-image and image editing operations
  • Your callback endpoint should accept POST requests with JSON payload containing image results
  • For detailed callback format and implementation guide, see Image Generation/Editing Callbacks
  • Alternatively, use the Get Image Details endpoint to poll task status
Example:

"https://your-callback-url.com/callback"

​
safetyTolerance
enum<integer>
default:2

For Image Generation Mode: Moderation level for inputs and outputs. Value ranges from 0 (most strict) to 6 (more permissive).

For Image Editing Mode: Moderation level for inputs and outputs. Value ranges from 0 (most strict) to 2 (balanced).

Default: 2

Available options:
0,
1,
2,
3,
4,
5,
6
Example:

2

​
watermark
string

Watermark identifier to add to the generated image.

  • Optional
  • If provided, a watermark will be added to the output image
Example:

"your-watermark-id"

Response

Request successful

​
code
enum<integer>

Response status code

  • 200: Success - Request has been processed successfully
  • 401: Unauthorized - Authentication credentials are missing or invalid
  • 402: Insufficient Credits - Account does not have enough credits to perform the operation
  • 404: Not Found - The requested resource or endpoint does not exist
  • 422: Validation Error - The request parameters failed validation checks.The request parameters are incorrect, please check the parameters.
  • 429: Rate Limited - Request limit has been exceeded for this resource
  • 455: Service Unavailable - System is currently undergoing maintenance
  • 500: Server Error - An unexpected error occurred while processing the request Server Error - The security tolerance level is out of range and should be 0-2 or 0-6
  • 501: Generation Failed - Image generation task failed
  • 505: Feature Disabled - The requested feature is currently disabled
Available options:
200,
401,
402,
404,
422,
429,
455,
500,
501,
505
​
msg
string

Error message when code != 200

Example:

"success"

​
data
object