v1

latestOpenAPI 3.0.02026-07-263014.2 KB

Generate or Edit Image

Create a new image generation or editing task using the Flux Kontext AI model.

Usage Modes

Text-to-Image Generation
- Provide prompt and aspectRatio
- Model will generate a new image based on the text description
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

post/api/v1/flux/kontext/generate

Request body

promptstring 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

enableTranslationboolean

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

uploadCnboolean

(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.

inputImagestring 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

aspectRatio'21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16'

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:

Ratio	Format Type	Common Use Cases
21:9	Ultra-wide	Cinematic displays, panoramic views
16:9	Widescreen	HD video, desktop wallpapers
4:3	Standard	Traditional displays, presentations
1:1	Square	Social media posts, profile pictures
3:4	Portrait	Magazine layouts, portrait photos
9:16	Mobile Portrait	Smartphone wallpapers, stories

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

outputFormat'jpeg' | 'png'

Output image format.

promptUpsamplingboolean

If true, performs upsampling on the prompt
May increase processing time

model'flux-kontext-pro' | 'flux-kontext-max'

Model version to use for generation.

Available Options:

Model	Description
flux-kontext-pro	Standard model with balanced performance
flux-kontext-max	Enhanced model with advanced capabilities

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

callBackUrlstring 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

safetyTolerance0 | 1 | 2 | 3 | 4 | 5 | 6

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

watermarkstring

Watermark identifier to add to the generated image.

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

Example request

{
  "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"
}

Response

Request successful

code200 | 401 | 402 | 404 | 422 | 429 | 455 | 500 | 501 | 505

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
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

msgstring

Error message when code != 200

Example response

{
  "msg": "success",
  "data": {
    "taskId": "task12345"
  }
}