FLUX Kontext API: Build and Compare Image Edits

For the documented FLUX Kontext operation on PiAPI, use model: "Qubico/flux1-dev-advanced", task_type: "kontext", and supply the source as input.image. The prompt describes the edit. When making a second revision, choose deliberately whether its input should be the original image or an accepted previous result.

This guide covers request preparation and comparison of revisions using the PiAPI Kontext specification checked on October 24, 2026. It includes no generated examples or quality benchmark. The sample prompts describe intended edits, not verified outcomes.

Use the Kontext contract for the edit

The Kontext specification names Qubico/flux1-dev-advanced as its available runtime and kontext as its task type. Its required input fields are prompt and image. The image field accepts an image URL or a base64 string. The example below uses a remotely readable HTTPS URL.

The separately documented image-to-image operation uses img2img and exposes controls such as denoise. Those fields are not an interchangeable Kontext recipe. Build the body for the selected operation instead of copying every control from another Flux form. The Flux first-call guide covers the broader runtime choice and initial task workflow.

For Kontext, the specification also lists width, height, seed, and steps. It gives a default of 28 steps and a maximum of 40, with seed: -1 indicating random seed selection. These are request controls; they are not promises that a particular edit will succeed or remain identical across future service versions.

Prepare a request with your own source image

Save this Python 3 script as kontext-request.py. Set PIAPI_SOURCE_IMAGE_URL to an HTTPS image URL you may process. This local helper writes JSON and checks the URL’s shape; it does not upload an image, submit a generation task, or prove the URL is reachable by the service.

import argparse
import json
import os
from urllib.parse import urlsplit

parser = argparse.ArgumentParser()
parser.add_argument("prompt")
parser.add_argument("--seed", type=int, default=-1)
args = parser.parse_args()
source = os.environ.get("PIAPI_SOURCE_IMAGE_URL", "")
url = urlsplit(source)
if url.scheme != "https" or not url.netloc:
    parser.error("Set PIAPI_SOURCE_IMAGE_URL to an accessible HTTPS image URL")
if not args.prompt.strip():
    parser.error("Supply a non-empty editing instruction")

print(json.dumps({
    "model": "Qubico/flux1-dev-advanced",
    "task_type": "kontext",
    "input": {
        "prompt": args.prompt,
        "image": source,
        "width": 1024,
        "height": 1024,
        "steps": 28,
        "seed": args.seed
    }
}, indent=2))

python3 kontext-request.py   'Change the mug to matte red. Preserve its shape, handle, and the background.'   --seed 42 > kontext-red-mug.json

This example requests a square 1024 × 1024 output. Choose a source and output dimensions appropriate for your application, and inspect the framing in the returned image. For an input containing a mug, the prompt separates the requested change from the features to preserve; preservation still needs to be checked in the output.

Submit the reviewed JSON once to POST https://api.piapi.ai/api/v1/task with an X-API-Key header from your backend. Use your account’s real key without placing it in browser code, committed source, or public logs. Consult the current operation documentation and account billing information before sending multiple revisions; this guide makes no price or license claim.

Choose between branching and chaining

Branch from the original when comparing alternatives. For example, prepare one red-mug request and one blue-mug request using the same source URL, dimensions, steps, and chosen seed. Change the color instruction only. This comparison is easier to interpret because the second candidate does not inherit changes introduced by the first.

Chain from an accepted result when adding another edit to that result. After accepting the red mug, make its saved output image the next input.image, then request a new background. Passing the original image again would ask the model to work from the original, even if your application labels the job “revision two.”

An example sequence is: original → red mug → red mug with a light gray background. A branch comparison is: original → red mug and original → blue mug. These arrows describe your application’s chosen inputs; the API does not infer this revision history from your filenames.

Retain the original image as well as each accepted intermediate result. Chained edits can introduce changes beyond the requested feature. If the mug handle or logo changes, return to the last acceptable source and narrow the next instruction. Increasing the number of edits is not itself a quality improvement.

Record completion and inspect the output

Save data.task_id from creation and retrieve the same task through GET /api/v1/task/{task_id}. Wait for its terminal status before treating the output as ready. The Kontext response schema documents data.output.image_url for a single image and data.output.image_urls for multiple images. Handle the response shape actually returned instead of assuming both are always present.

For every revision, keep the source asset identifier, parent revision if any, exact request, task ID, returned output location, and your acceptance decision. Save accepted image bytes to storage you control if the application needs them later. The generated-file storage guide covers retaining output instead of relying only on a remote URL.

Check the requested change, object shape, text and logos, background, and output framing. For a color edit, record whether the color changed and whether unrelated details stayed acceptable. A fixed seed and an unchanged prompt help describe an experiment; they do not replace viewing the result or establish deterministic behavior.

Resolve input problems before another submission

If the service cannot fetch the input, check that the URL points to an image rather than a sign-in page or local preview. If the result uses the wrong revision, inspect the exact input.image value saved with that task. If an unsupported control appears in the body, compare it with the Kontext specification rather than adding fields from img2img.

If submission or polling times out, preserve the available task ID and request receipt. Reconcile the task before creating another paid request; the retry-safety guide explains that boundary. Continue with the Kontext API documentation when you are ready to submit the reviewed edit.