API reference

Flux Kontext API

Generate or edit images asynchronously. Submit a task, retain its task_id, then poll until the status is final.

Authentication

Send your project API key as a Bearer token on both create and status requests.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Models and credits

Model	Text	Edit
flux-kontext-pro	2	7
flux-kontext-max	7	12

A request is treated as an edit when input_image, inputImage, or images is present.

POST

/generate

Compatibility endpoint: POST https://fluxkontextapi.org/generate. The versioned alias /v1/generate behaves the same.

Request body

Field	Required	Description
description / prompt	Yes	Image instruction, up to 5,000 characters.
model	No	`flux-kontext-pro` or `flux-kontext-max`.
aspect_ratio	No	`1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9`, or `16:21`.
format	No	`jpeg` or `png`.
auto_translate_to_en	No	Defaults to `true`.
enhance_prompt	No	Defaults to `false`.
input_image	Edit only	A public image URL or an array of up to eight URLs.

curl -X POST https://fluxkontextapi.org/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A simple red circle on a white background",
    "model": "flux-kontext-pro",
    "aspect_ratio": "1:1",
    "format": "jpeg",
    "auto_translate_to_en": true,
    "enhance_prompt": false
  }'

Success response

The task identifier is returned as data.task_id, not data.data.taskId.

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n110_8d3f...",
    "status": "IN_PROGRESS"
  },
  "task_id": "n110_8d3f..."
}

GET

/feed

Poll GET https://fluxkontextapi.org/feed?task_id=.... The versioned alias is /v1/status.

curl "https://fluxkontextapi.org/feed?task_id=n110_8d3f..." \
  -H "Authorization: Bearer YOUR_API_KEY"

Status values

status	status_code	Meaning
SUBMITTING	3	Credit charge or provider submission is being verified.
IN_PROGRESS	3	Provider accepted the task and generation is running.
SUCCESS	1	Final image is available in `response` and `result_image_url`.
FAILED	2	Final failure. Charged credits are automatically refunded.

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n110_8d3f...",
    "status": "SUCCESS",
    "status_code": 1,
    "consumed_credit": 2,
    "refund_status": "NOT_REQUIRED",
    "response": ["https://example.com/result.jpg"],
    "result_image_url": "https://example.com/result.jpg"
  }
}

JavaScript quick start

const headers = {
  Authorization: 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
}

const createResponse = await fetch('https://fluxkontextapi.org/generate', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    description: 'A simple red circle on a white background',
    model: 'flux-kontext-pro',
    aspect_ratio: '1:1',
    format: 'jpeg'
  })
})
const created = await createResponse.json()
const taskId = created.data.task_id

while (true) {
  const response = await fetch(
    `https://fluxkontextapi.org/feed?task_id=${encodeURIComponent(taskId)}`,
    { headers }
  )
  const result = await response.json()
  if (result.data.status === 'SUCCESS') break
  if (result.data.status === 'FAILED') throw new Error(result.data.error_message)
  await new Promise(resolve => setTimeout(resolve, 5000))
}

Failures and refunds

Provider rejection, generation failure, and unrecoverable timeout transition the task to FAILED. The original charge is returned using an idempotent refund key, so webhook, polling, and background reconciliation cannot refund the same task twice. Check refund_status for REFUNDED.