FLUX Kontext Image Generation and Editing

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-kontext-pro",
    "prompt": "Change the hair color to blue",
    "image_urls": ["https://example.com/portrait.jpg"],
    "size": "1:1",
    "output_format": "png"
  }'

import requests

url = "https://api.apimart.ai/v1/images/generations"

payload = {
    "model": "flux-kontext-pro",
    "prompt": "Change the hair color to blue",
    "image_urls": ["https://example.com/portrait.jpg"],
    "size": "1:1",
    "output_format": "png"
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const url = "https://api.apimart.ai/v1/images/generations";

const payload = {
  model: "flux-kontext-pro",
  prompt: "Change the hair color to blue",
  image_urls: ["https://example.com/portrait.jpg"],
  size: "1:1",
  output_format: "png"
};

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});

console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2"
    }
  ]
}

{
  "error": {
    "code": 401,
    "message": "Authentication failed, please check your API key",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient balance, please top up",
    "type": "payment_required"
  }
}

POST

images

generations

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-kontext-pro",
    "prompt": "Change the hair color to blue",
    "image_urls": ["https://example.com/portrait.jpg"],
    "size": "1:1",
    "output_format": "png"
  }'

import requests

url = "https://api.apimart.ai/v1/images/generations"

payload = {
    "model": "flux-kontext-pro",
    "prompt": "Change the hair color to blue",
    "image_urls": ["https://example.com/portrait.jpg"],
    "size": "1:1",
    "output_format": "png"
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const url = "https://api.apimart.ai/v1/images/generations";

const payload = {
  model: "flux-kontext-pro",
  prompt: "Change the hair color to blue",
  image_urls: ["https://example.com/portrait.jpg"],
  size: "1:1",
  output_format: "png"
};

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});

console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2"
    }
  ]
}

{
  "error": {
    "code": 401,
    "message": "Authentication failed, please check your API key",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient balance, please top up",
    "type": "payment_required"
  }
}

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-kontext-pro",
    "prompt": "Change the hair color to blue",
    "image_urls": ["https://example.com/portrait.jpg"],
    "size": "1:1",
    "output_format": "png"
  }'

import requests

url = "https://api.apimart.ai/v1/images/generations"

payload = {
    "model": "flux-kontext-pro",
    "prompt": "Change the hair color to blue",
    "image_urls": ["https://example.com/portrait.jpg"],
    "size": "1:1",
    "output_format": "png"
}

headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const url = "https://api.apimart.ai/v1/images/generations";

const payload = {
  model: "flux-kontext-pro",
  prompt: "Change the hair color to blue",
  image_urls: ["https://example.com/portrait.jpg"],
  size: "1:1",
  output_format: "png"
};

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});

console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2"
    }
  ]
}

{
  "error": {
    "code": 401,
    "message": "Authentication failed, please check your API key",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Insufficient balance, please top up",
    "type": "payment_required"
  }
}

Supported Models

Model	Description
`flux-kontext-pro`	Context-aware image generation and editing for general-purpose workflows.
`flux-kontext-max`	Higher-quality context-aware image generation and editing.

Both models support text-to-image generation without reference images and image editing with reference images.

Authorizations

string

required

All endpoints require Bearer Token authentication.Get an API key from API Key Management, then add it to the request header:

Authorization: Bearer YOUR_API_KEY

Body

string

required

Model name:

flux-kontext-pro
flux-kontext-max

boolean

default:"false"

Whether to run content moderation before submitting the image task.

true: use omni-moderation-latest to review prompts and input images
false or omitted: do not send a moderation request, adding no moderation cost or latency (default)

string

required

Text description of the image to generate or the edit to apply to the reference images.

array

Reference images for image editing. Publicly accessible image URLs and Base64 input are supported.

Maximum: 4 images
The output plus all reference images must not exceed 9 MP in total

If a reference URL cannot be accessed publicly, the task may return only temporarily unavailable dependency. When this happens, first check hotlink protection, access permissions, and expired signatures.

string

default:"1:1"

Output aspect ratio. A pixel string such as 1024x1536 is also accepted, but Kontext maps it to the closest supported ratio rather than producing those exact pixel dimensions. Supported aspect ratios and automatic mode:

1:1 (default)
4:3
3:4
16:9
9:16
3:2
2:3
21:9
9:21
auto - Follow the reference image aspect ratio

When size is set to auto, the output follows the reference image’s aspect ratio if image_urls is provided. Without a reference image, it uses the default 1:1 ratio.

Kontext does not support width or height; supplying either field causes the task to fail. Use size to control the aspect ratio. resolution has no effect for Kontext, whose output remains approximately 1 MP.

string

default:"png"

Output image encoding. Supported values: png, jpeg, and webp.

string

OpenAI-compatible response-shape field. It accepts only url or b64_json and does not change the image encoding. When both fields are supplied, output_format takes priority.

integer

default:"1"

Number of images generated per task. The only supported value is 1; submit multiple tasks concurrently if you need multiple images.

integer

Random seed. Reuse the same seed and parameters for reproducible output; omit it to use a random seed.

boolean

default:"false"

Whether to enhance and rewrite the prompt before generation.Set this parameter explicitly to false to disable prompt rewriting.

integer

default:"2"

Safety tolerance from 0 to 6. Higher values are more permissive.

Supported Aspect Ratios

Aspect ratio	Orientation
`1:1`	Square (default)
`4:3`	Landscape
`3:4`	Portrait
`16:9`	Widescreen landscape
`9:16`	Vertical portrait
`3:2`	Classic landscape
`2:3`	Classic portrait
`21:9`	Ultra-wide landscape
`9:21`	Ultra-tall portrait

Actual Output Dimensions

Ratio	Actual output dimensions
`1:1`	1024×1024
`4:3`	1184×880
`3:4`	880×1184
`16:9`	1392×752
`9:16`	752×1392
`3:2`	1248×832
`2:3`	832×1248
`21:9`	1568×672
`9:21`	672×1568

Usage Examples

Text-to-image generation

{
  "model": "flux-kontext-pro",
  "prompt": "A cozy reading nook with warm lamplight",
  "size": "4:3"
}

Image editing

{
  "model": "flux-kontext-max",
  "prompt": "Replace the background with a beach while preserving the person",
  "image_urls": ["https://example.com/portrait.jpg"],
  "size": "16:9",
  "output_format": "webp"
}

Multiple reference images

{
  "model": "flux-kontext-pro",
  "prompt": "Place the product from the first image into the room from the second image",
  "image_urls": [
    "https://example.com/product.jpg",
    "https://example.com/room.jpg"
  ],
  "size": "4:3"
}

Response

integer

Response status code.

array

Submission result array.

Show Properties

string

Submission status. A successfully accepted task returns submitted.

string

Unique task identifier. Use it to poll the task endpoint.

Retrieve the Result

Poll GET /v1/tasks/{task_id} until the task reaches completed or failed. See the Task Status API for the complete response schema. Task statuses:

Status	Meaning
`submitted` / `pending`	Accepted or queued; continue polling.
`processing`	Image generation is in progress; continue polling.
`completed`	Generation succeeded; the image is available in `result.images`.
`failed`	Generation failed; read `data.error.message`. The task is fully refunded.

A completed task includes one generated image:

{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://upload.apimart.ai/f/image/xxxxxxxx-flux-kontext.png"],
          "expires_at": 1785220083
        }
      ]
    }
  }
}

The image URL is data.result.images[0].url[0]. Its expiration is defined by the Unix timestamp in data.result.images[0].expires_at; download the image before that time.

Invalid parameters and failed tasks

Invalid model parameters do not produce a synchronous 4xx response. The submission still returns HTTP 200 with a task_id; keep polling until the task becomes failed, then read the specific reason from data.error.message. Failed tasks are fully refunded.

{
  "code": 200,
  "data": {
    "status": "failed",
    "error": {
      "type": "task_failed",
      "code": "task_failed",
      "message": "width/height are not supported by flux-kontext-pro"
    }
  }
}

error.code is always task_failed; the specific reason is in error.message.

Notes

Tasks are processed asynchronously. The submission response returns a task_id for polling.
n defaults to 1, which is the only supported value.
Reference images may use publicly accessible image URLs or Base64 input.
Up to 4 reference images are supported, subject to the 9 MP combined input-and-output limit.
Set prompt_upsampling: false explicitly to disable prompt rewriting.
Result URL expiration is determined by the expires_at value returned in the task response.
width and height cause the task to fail; resolution does not change the approximately 1 MP output; a pixel-string size maps to the closest supported ratio.
Invalid model parameters are returned asynchronously: poll until failed and read data.error.message.

Overview

Models

Text Series

Image Series

Video Series

Audio Series

Moderation Series

Upload Management

Task Management

Account Management

FLUX Kontext Image Generation and Editing

Supported Models

Authorizations

Body

Supported Aspect Ratios

Actual Output Dimensions

Usage Examples

Text-to-image generation

Image editing

Multiple reference images

Response

Retrieve the Result

Invalid parameters and failed tasks

Notes

​Supported Models

​Authorizations

​Body

​Supported Aspect Ratios

​Actual Output Dimensions

​Usage Examples

​Text-to-image generation

​Image editing

​Multiple reference images

​Response

​Retrieve the Result

​Invalid parameters and failed tasks

​Notes

Supported Models

Authorizations

Body

Supported Aspect Ratios

Actual Output Dimensions

Usage Examples

Text-to-image generation

Image editing

Multiple reference images

Response

Retrieve the Result

Invalid parameters and failed tasks

Notes