black-forest-labs/flux-3/image-to-image

Image to Image

Black Forest Labs FLUX 3 makes precise local edits from written instructions, changing only what you ask while the rest of the image stays intact. Combine up to 10 reference images into one scene, output at 1K, 2K or 4K or as quick square drafts, and keep the input framing with auto aspect ratio or pick from 14 ratios.

Try it Get API keyOpenAPI llms.txt

Prompt *

Image Urls *

1 *

Aspect Ratio

Resolution

More settings (3)

Enable prompt expansion

Output Format

Version

ResultExampleSign in to try

$0.024 / megapixel · billed by each image's actual pixels

Example — generated from this input

Change only the middle coffee bag: make it deep plum instead of terracotta and change its label to read "SUMMER DUSK" in the same black type, keeping the smaller "Single Origin" line. Keep the other two bags, the shelf, the wall, the lighting and the camera angle exactly the same.

Pricing

Unit price $0.024 / megapixel

Billed by the actual pixels of each image; larger sizes and more images cost more. 1024×1024 is about 1 megapixel.

Typically about $0.024 per request at default settings.

Each request temporarily reserves $0.024; you are charged for actual usage, usually within a minute: any unused amount is released and any usage above it is charged to your balance, even if that takes it below zero; while your balance is below zero, new requests are paused until a top-up covers it.

Failed generations are not charged.

API

Submit generation requests with this model ID.

POST/v1/model-tasks

black-forest-labs/flux-3/image-to-image

Request body

{
  "model": "black-forest-labs/flux-3/image-to-image",
  "input": {
    "prompt": "Change only the middle coffee bag: make it deep plum instead of terracotta and change its label to read \"SUMMER DUSK\" in the same black type, keeping the smaller \"Single Origin\" line. Keep the other two bags, the shelf, the wall, the lighting and the camera angle exactly the same.",
    "aspect_ratio": "auto",
    "enable_prompt_expansion": false,
    "image_urls": [
      "https://pub-a7287c8d5de944d984e22a5bd3ab9bbe.r2.dev/uploads/capability-demo-4b100561a17d0564bb7b21a3e6c75ceb.jpg"
    ],
    "output_format": "jpeg",
    "resolution": "1k",
    "version": "latest"
  }
}

Input schema

Parameter	Type	Requirement	Default
image_urls	array	Required	—
prompt	string	Required	—
aspect_ratio	string	Optional	auto
enable_prompt_expansion	boolean	Optional	false
output_format	string	Optional	jpeg
resolution	string	Optional	1k
version	string	Optional	latest

Response

The API returns a result or a pollable asynchronous task. See the examples and Schema below for the response mode and result fields.

Asynchronous task

Submit response

HTTP 202

/v1/model-tasksapplication/json

{
  "id": "task_example",
  "model": "black-forest-labs/flux-3/image-to-image",
  "status": "queued"
}

Status response

HTTP 200

/v1/model-tasks/{id}application/json

{
  "id": "task_example",
  "model": "black-forest-labs/flux-3/image-to-image",
  "status": "completed",
  "output": {
    "images": [
      {
        "url": "https://api.musespan.com/v1/model-tasks/task_example/artifacts/0"
      }
    ]
  }
}

File download

HTTP 200

/v1/model-tasks/{id}/artifacts/{index}Generated image (e.g. image/png)

When the task completes, file URLs in output point to this endpoint, numbered from 0. Send the same API key (Authorization header) when downloading.

Error response

HTTP 400

/v1/model-tasksapplication/json

{
  "error": {
    "code": "invalid_input",
    "message": "The input does not match this model's input schema. Check the model's API documentation.",
    "type": "invalid_request_error"
  }
}

Code examples

Async submission returns a task ID. Poll until status is completed, then retrieve the generated content from the result. Get your API key in the console.

# Use a new directory for each new generation. Rerunning here continues this task.
set -eu
test -s model-task-id.txt || python3 -c "import uuid; print(uuid.uuid4())" > model-task-id.txt
REQUEST_ID=$(cat model-task-id.txt)
# Idempotent: resending the same bytes with the same ID never charges twice.
curl --fail-with-body --retry 3 --retry-connrefused --request POST 'https://api.musespan.com/v1/model-tasks' \
  --header "Authorization: Bearer $MUSESPAN_API_KEY" \
  --header "X-Request-Id: $REQUEST_ID" \
  --header "Content-Type: application/json" \
  --data '{"model":"black-forest-labs/flux-3/image-to-image","input":{"prompt":"Change only the middle coffee bag: make it deep plum instead of terracotta and change its label to read \"SUMMER DUSK\" in the same black type, keeping the smaller \"Single Origin\" line. Keep the other two bags, the shelf, the wall, the lighting and the camera angle exactly the same.","aspect_ratio":"auto","enable_prompt_expansion":false,"image_urls":["https://pub-a7287c8d5de944d984e22a5bd3ab9bbe.r2.dev/uploads/capability-demo-4b100561a17d0564bb7b21a3e6c75ceb.jpg"],"output_format":"jpeg","resolution":"1k","version":"latest"}}'
# Poll every 5 seconds for up to 25 minutes until status is completed or failed.
# Still queued (with queue_position) 5 minutes after submission: failed with queue_timeout, not charged.
# No result 15 minutes after acceptance (or no confirmation 15 minutes after submission): failed with generation_timeout, not charged.
# Any failure is final: generate again in a new directory (a new X-Request-Id).
# A 404 means the POST did not arrive: rerun this script to resend it with the same ID.
curl --fail-with-body 'https://api.musespan.com/v1/model-tasks/'"$REQUEST_ID"'' --header "Authorization: Bearer $MUSESPAN_API_KEY"