Skip to main content
POST
/
v1
/
ai
/
text-to-image
/
flux-kontext-pro
Flux Kontext Pro - Create image from text
curl --request POST \
  --url https://api.freepik.com/v1/ai/text-to-image/flux-kontext-pro \
  --header 'Content-Type: application/json' \
  --header 'x-freepik-api-key: <api-key>' \
  --data '
{
  "prompt": "a beautiful sunset over the ocean with dramatic clouds",
  "input_image": "https://example.com/reference-image.jpg",
  "prompt_upsampling": false,
  "seed": 123,
  "guidance": 3,
  "steps": 50,
  "aspect_ratio": "square_1_1",
  "safety_tolerance": 2,
  "output_format": "jpeg",
  "webhook_url": "https://www.example.com/webhook"
}
'
{
  "data": {
    "task_id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "status": "CREATED"
  }
}

Authorizations

​
x-freepik-api-key
string
header
required

Your Freepik API key. Required for authentication. Learn how to obtain an API key

Body

application/json
​
prompt
string
required

Text description of the image you want to generate.

FLUX Kontext Pro is an advanced text-to-image model that excels at understanding context and generating high-quality images. It supports optional image input to guide the generation.

Tips for better results:

  • Be specific about subjects, scenes, and visual details
  • Describe lighting, atmosphere, and mood
  • Mention art style or photographic techniques if desired
Example:

"a beautiful sunset over the ocean with dramatic clouds"

​
input_image
string<uri> | null

Optional URL to an input image that will guide the generation process. The model will use this image as a reference while generating the output.

Example:

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

​
prompt_upsampling
boolean
default:false

Whether to perform upsampling on the prompt. If active, automatically modifies the prompt for more creative generation.

​
seed
integer | null

Optional seed for reproducibility. If not provided, a random seed will be used.

​
guidance
number | null
default:3

Guidance scale for the generation. Higher values make the model follow the prompt more closely.

Required range: 1 <= x <= 10
​
steps
integer | null
default:50

Number of inference steps. More steps generally produce higher quality but take longer.

Required range: 1 <= x <= 100
​
aspect_ratio
enum<string>
default:square_1_1

Image size with the aspect ratio. The aspect ratio is the proportional relationship between an image's width and height, expressed as *_width_height (e.g., square_1_1, widescreen_16_9). It is calculated by dividing the width by the height.
If not present, the default is square_1_1.

Available options:
square_1_1,
classic_4_3,
traditional_3_4,
widescreen_16_9,
social_story_9_16,
standard_3_2,
portrait_2_3,
horizontal_2_1,
vertical_1_2,
social_post_4_5
Example:

"square_1_1"

​
safety_tolerance
integer
default:2

Tolerance level for input and output moderation. Between 0 and 6, 0 being most strict, 6 being least strict.

Required range: 0 <= x <= 6
​
output_format
enum<string> | null

Format of the output image

Available options:
jpeg,
png
​
webhook_url
string<uri>

Optional callback URL that will receive asynchronous notifications whenever the task changes status. The payload sent to this URL is the same as the corresponding GET endpoint response, but without the data field.

Example:

"https://www.example.com/webhook"

Response

OK - Task created successfully

​
data
object
required
Example:
{
  "task_id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
  "status": "CREATED"
}