Flux 2 Turbo Edit API Documentation

Flux 2 Turbo Edit API Documentation

Playground

FLUX 2 turbo Edit delivers ultra-fast image-to-image editing from Black Forest Labs—apply natural-language instructions and exact hex color control for consistent, studio-quality results at turbo speed. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

FLUX 2 Turbo Edit (wavespeed-ai/flux-2-turbo/edit) is a fast, practical image-to-image editing model for applying natural-language changes to an existing image (for example: lighting, color, props, background, or style), while keeping the original composition and identity cues stable.

It’s well suited for high-volume creative workflows where you want reliable edits with minimal configuration—provide an input image, describe the change, and iterate quickly.

Key capabilities

• Prompt-guided image editing (image-to-image) Apply targeted edits using plain-language instructions (for example: “make it winter”, “change the background to studio gray”, “increase contrast while keeping the face and pose”).

• Composition- and identity-preserving updates Optimized for “update, not regenerate” workflows, helping preserve layout, subjects, and overall visual identity across edits.

• Repeatable results via seed control Use a fixed seed to reproduce the same edit or generate controlled variations for testing and comparison.

• Flexible image inputs (up to 3 images) Supports 1–3 input images, allowing reference-based edits or multi-image context.

• Production-friendly outputs Results can be returned as hosted image URLs by default, or as Base64-encoded data for direct embedding.

Parameters and how to use

• prompt: (required) The edit instruction describing what you want to change.
• images: (required) Array of input image URLs (1–3 items) to edit.
• size: Output size in pixels as "width*height".
• seed: Random seed for generation (-1 for random; fixed integer for repeatability).
• enable_sync_mode: If true, waits for completion and returns the result in the response (API only).
• enable_base64_output: If true, returns Base64-encoded output instead of a URL (API only).

Prompt

Write your prompt like a concise edit brief:

1. State the change clearly Example: “Change the weather to winter. Add light snowfall and frosty breath.”
2. Explicitly say what must stay the same Example: “Keep the same person, pose, face, and camera framing.”
3. Specify visual attributes Mention lighting, materials, mood, or style (for example: “soft studio lighting”, “high-contrast cinematic look”).
4. Use exact values for precision For branding or color accuracy, specify exact values such as hex color codes.

Media (Images)

• Provide images as publicly accessible image URLs.
• Supports 1 to 3 images per request.

Other parameters

• size Controls output resolution using "width*height". Typical values:

• "1024*1024" for square assets

• "1536*1024" for wide banners

• "1024*1536" for portrait layouts

• seed

• -1 for a new variation each run

• A fixed integer (for example: 12345) for repeatable edits

After you finish configuring the parameters, click Run, preview the result, and iterate if needed.

Pricing

Pricing starts at $0.048 per request, including one reference image. Each additional reference image costs $0.008.

Notes

• For the most stable results, make one type of change at a time and reuse the same seed while iterating.
• If edits change too much of the original image, reinforce constraints in the prompt (for example: “keep the same composition, identity, and proportions”).

Related Models

• FLUX.2 Dev Edit – A lightweight, cost-efficient FLUX.2 editing variant.
• FLUX.2 Flex Edit – A more flexible option for creative and stylistic exploration.
• FLUX.2 Pro Edit – Higher-fidelity edits designed for production and brand assets.
• FLUX.2 Max Edit – The highest-quality FLUX.2 editing model for detail-critical work.

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",
  "images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ]
}
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-2-turbo/edit" \
  -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