FLUX Kontext Image Generation and Editing

Request example

curl --request POST \
  --url https://api.openveer.com/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.openveer.com/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.openveer.com/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());

Response example

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

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

Authorizations

Authorization: Bearer YOUR_API_KEY

Body

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.

Supported Aspect Ratios

Actual Output Dimensions

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

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:

A completed task includes one generated image:

{
  "code": 200,
  "data": {
    "id": "task_01KFG5BBFNK1YQDTJDZY0P0QT2",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": ["https://upload.openveer.com/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

1. Tasks are processed asynchronously. The submission response returns a task_id for polling.
2. n defaults to 1, which is the only supported value.
3. Reference images may use publicly accessible image URLs or Base64 input.
4. Up to 4 reference images are supported, subject to the 9 MP combined input-and-output limit.
5. Set prompt_upsampling: false explicitly to disable prompt rewriting.
6. Result URL expiration is determined by the expires_at value returned in the task response.
7. 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.
8. Invalid model parameters are returned asynchronously: poll until failed and read data.error.message.

This documentation is built and hosted on Mintlify, a developer documentation platform.