FLUX Kontext API: Integrate FLUX.1 Kontext [pro] with fal.ai

Direct answer

“FLUX Kontext API” does not identify one universal endpoint. This guide covers fal.ai’s hosted fal-ai/flux-pro/kontext route for FLUX.1 Kontext [pro]—not a direct Black Forest Labs API integration, ComfyUI’s Partner Node, or the dev and max variants. The request requires a text prompt and an image_url. fal lists this route at $0.04 per image; check the model page and your account billing details for current charges. (fal.ai)

What this endpoint does

The Pro route accepts an instruction and a reference image for image editing. For example, fal’s model documentation shows a prompt to put a donut next to flour. Treat prompts as instructions to try, not guarantees of an exact edit. (fal.ai)

This guide is specific to the Pro editing endpoint. Other Kontext identifiers shown in fal’s gallery do not establish that they share this route’s API contract, price, or availability. Check the selected model’s own documentation before switching variants.

Prerequisites

• A fal account and API key. fal recommends setting the key as FAL_KEY rather than hardcoding it. For raw HTTP requests, include it as Authorization: Key $FAL_KEY. (fal.ai)
• A source image available at a URL the service can access. The model request uses the image_url field. If your image is local, upload it using a fal-supported file workflow first. (fal.ai)
• curl and jq for the command-line example.

Set your key in the environment; do not commit it to a repository or expose it in browser code:

export FAL_KEY="your-fal-api-key"

Submit an image edit

For the asynchronous queue flow, submit a POST request to https://queue.fal.run/fal-ai/flux-pro/kontext. The submission response includes request_id, status_url, and response_url; use the URLs returned by fal rather than constructing them yourself. (fal.ai)

Create a request file, replacing the example image URL with one fal can access:

: "${FAL_KEY:?Set FAL_KEY before submitting a request}"

cat > request.json <<'JSON'
{
  "prompt": "Change the car color to red while keeping the rest of the image unchanged.",
  "image_url": "https://example.com/source-image.jpg"
}
JSON

if ! curl --fail-with-body --silent --show-error \
  --request POST \
  --url "https://queue.fal.run/fal-ai/flux-pro/kontext" \
  --header "Authorization: Key $FAL_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json \
  --output submit.json; then
  echo "Submission failed; response body, if any:" >&2
  cat submit.json >&2 2>/dev/null || true
  exit 1
fi

STATUS_URL=$(jq -er '.status_url | strings | select(length > 0)' submit.json) || {
  echo "Submission response is invalid or has no status_url" >&2
  cat submit.json >&2
  exit 1
}
RESPONSE_URL=$(jq -er '.response_url | strings | select(length > 0)' submit.json) || {
  echo "Submission response is invalid or has no response_url" >&2
  cat submit.json >&2
  exit 1
}

The prompt above is illustrative; it is not a special required phrase. fal documents prompt and image_url in its model example. This article intentionally omits optional-field defaults and ranges rather than treating gallery settings as API requirements. Consult the model’s current schema before adding optional parameters. (fal.ai)

Check status and retrieve the result

Poll the returned status_url. The documented queue states are IN_QUEUE, IN_PROGRESS, and COMPLETED. A failed or cancelled request can also reach COMPLETED, so fetch the result and check it for an error before treating it as a successful edit. (fal.ai)

This example saves each response, stops on HTTP or JSON errors, rejects unexpected statuses, and bounds polling to 90 attempts at two-second intervals. Those polling values are example client choices—not fal limits. On success, it checks for an image URL and downloads the image:

completed=false

for attempt in {1..90}; do
  if ! curl --fail-with-body --silent --show-error \
    --header "Authorization: Key $FAL_KEY" \
    "$STATUS_URL" --output status.json; then
    echo "Status request failed; response body, if any:" >&2
    cat status.json >&2 2>/dev/null || true
    exit 1
  fi

  STATUS=$(jq -er '.status | strings' status.json) || {
    echo "Status response is invalid or has no status field" >&2
    cat status.json >&2
    exit 1
  }

  case "$STATUS" in
    IN_QUEUE|IN_PROGRESS)
      sleep 2
      ;;
    COMPLETED)
      completed=true
      break
      ;;
    *)
      echo "Unexpected queue status: $STATUS" >&2
      exit 1
      ;;
  esac
done

if [ "$completed" != true ]; then
  echo "Polling window ended before the request completed; check status_url again later." >&2
  exit 1
fi

if ! curl --fail-with-body --silent --show-error \
  --header "Authorization: Key $FAL_KEY" \
  "$RESPONSE_URL" --output result.json; then
  echo "Result request failed; response body, if any:" >&2
  cat result.json >&2 2>/dev/null || true
  exit 1
fi

IMAGE_URL=$(jq -er '
  if has("error") or has("detail") then
    error("model result contains an error")
  else
    .images[0].url | strings | select(length > 0)
  end
' result.json) || {
  echo "Result is not a successful response with an image URL:" >&2
  cat result.json >&2
  exit 1
}

if ! curl --fail-with-body --silent --show-error \
  "$IMAGE_URL" --output edited-image; then
  echo "Could not download the returned image." >&2
  exit 1
fi

echo "Edited image saved as edited-image"

fal documents that result retrieval returns the model response; if the model returned an error, the result operation returns that error. Check and handle the response body in your application as well. (fal.ai)

Required request fields and price

Field	Requirement	Use
prompt	Required	Text instruction for the edit.
image_url	Required	URL of the reference image.

fal lists $0.04 per image for this Pro route. This price is specific to the fal endpoint described here; do not apply it to other providers or Kontext variants. Check the model page and your account billing details before deployment. (fal.ai)

Production notes

• Keep the key server-side. Use an environment variable or another secrets-management method; do not expose the key in client-side code. (fal.ai)
• Check image-input requirements. The model page lists accepted file types as JPG, JPEG, PNG, WebP, GIF, AVIF, HEIC, and HEIF. It does not state a maximum input-image size in the listed model information, so confirm any size or input constraints in the current model documentation before deployment. (fal.ai)
• Plan for account concurrency. fal documents a global, account-level concurrency limit: new accounts start at two concurrent requests, limits scale with paid invoices, and fal may also apply per-endpoint limits to high-demand models. Requests over the concurrency limit wait in the queue; check your current limit in the fal dashboard. The documented limit is account-dependent, not a single universal requests-per-minute figure. (fal.ai)
• Check results promptly. fal documents result retention of one hour after completion, or six minutes for results of 10 KB or larger. If payload storage is enabled, the result remains available for the configured storage period. Persist the image or its URL as appropriate for your workflow. (fal.ai)
• Separate this API from wrappers and other routes. Community ComfyUI node controls are not the raw fal request schema. Together’s statement that its FLUX.1 Kontext [dev] model is unavailable on its Serverless API applies to that route only; it does not establish availability through other Together access methods. (fal.ai)

Use these instructions for fal.ai’s FLUX.1 Kontext [pro] image-edit endpoint. For another provider or variant, check that route’s own current model documentation for its endpoint, authentication, request schema, result handling, and billing.

Sources

Flux Pro Kontext API — fal

Submit a request to an endpoint path — fal Queue API

Queue API: Submit, Check Status, Get Results — fal

Get request result — fal Queue API

Concurrency Limits — fal

Inference API — fal

FLUX.1 Kontext [dev] — Together AI