Flux Kontext Dev Multi API Documentation

Flux Kontext Dev Multi API Documentation

Playground

Experimental FLUX.1 Kontext [dev] with multi-image handling for contextual multi-input inference and image workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

FLUX.1 Kontext Dev Multi extends instruction-based image editing to a multi-image workflow. You can provide up to 4 reference images alongside a text instruction, enabling richer context, stronger consistency, and more controllable edits across subjects, styles, and scenes—especially useful when one image alone is not enough to describe what you want.

Key capabilities

• Multi-image contextual editing with up to 4 reference images
• Better subject/style consistency by grounding edits in multiple references
• Supports both local edits (specific changes) and global edits (overall look)
• Ideal for iterative workflows: refine results step-by-step while keeping identity and style stable

Typical use cases

• Multi-reference character consistency (face/hair/outfit cues from multiple photos)
• Product edits with reference packs (angle, material, branding consistency)
• Style guidance from multiple exemplars (illustration style + lighting reference + texture reference)
• Scene recomposition while preserving subject identity
• Branding/text edits that must match reference typography and layout

Pricing

$0.03 per generation.

If you generate multiple outputs in one run, total cost = num_images × $0.03 Example: num_images = 4 → $0.12

Inputs and outputs

Input:

• Up to 4 reference images (upload or public URLs)
• One edit instruction (prompt)

Output:

• One or more edited images (controlled by num_images)

Parameters

• prompt: Edit instruction describing what to change and what to keep
• images: Up to 4 reference images
• width / height: Output resolution
• num_inference_steps: More steps can improve fidelity but increases latency
• guidance_scale: Higher values follow the prompt more strongly; too high may over-edit
• num_images: Number of variations generated per run
• seed: Fixed value for reproducibility; -1 for random
• output_format: jpeg or png
• enable_base64_output: Return BASE64 instead of a URL (API only)
• enable_sync_mode: Wait for generation and return results directly (API only)

Prompting guide

For multi-reference runs, be explicit about how each reference should be used:

Template: Use reference 1 for [identity]. Use reference 2 for [outfit/material]. Use reference 3 for [style/lighting]. Use reference 4 for [background/scene]. Keep [must-preserve]. Change [edit request]. Match [lighting/shadows/perspective].

Example prompts

• Use reference 1 for face identity and reference 2 for hairstyle. Keep the pose from the base image. Replace the background with a modern office and match lighting direction.
• Use reference 1 for the product shape and reference 2 for label design. Replace the label text with “WaveSpeedAI”, keeping typography, perspective, and print texture consistent.
• Use reference 3 as the style guide (soft illustration look) and reference 4 for lighting mood (golden hour). Preserve the subject identity from reference 1.

Best practices

• Provide clean references: sharp subjects, consistent lighting, minimal occlusion.
• Assign roles to references (identity vs. style vs. scene) to avoid conflicting signals.
• Make one change per run, then iterate for tighter control.
• Fix seed when you need stable comparisons across prompt variants.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "num_inference_steps": 28,
  "guidance_scale": 2.5,
  "num_images": 1,
  "output_format": "jpeg"
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/flux-kontext-dev/multi" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters