Make and edit images

Send a text prompt and get an image back, on the same key and base URL (https://api.fluxrouter.ai/v1) as your chat requests. You can also send one or more reference images and ask for an edit. Images are a paid ability, billed per image.

This page is about making images. To send an image to a model so it can describe or reason about it, see Vision and image inputs.

Pick a model#

Leave model out, or set it to flux-image, and you get the default. The models you can name, with their prices:

The same list comes from GET /v1/models: the image models have capability set to image, with a list_price_microcents per image. See List models and prices.

If you do not name a model, you can pick a price class with category: Standard (the default), Plus, Pro or Ultra. Flux chooses the model for that class.

Make an image#

From your agent, ask for an image and it calls image_generate on the Flux tools server. From your own code, send POST /v1/images/generations. Each example sets max_price, so the call is refused rather than charged if it would cost more than you allow.

claude mcp add --transport http flux-tools https://api.fluxrouter.ai/mcp-tools/ \
  --header "Authorization: Bearer sk-YOUR-FLUX-KEY"

[mcp_servers.flux-tools]
url = "https://api.fluxrouter.ai/mcp-tools/"
bearer_token_env_var = "FLUX_API_KEY"

{
  "mcpServers": {
    "flux-tools": {
      "url": "https://api.fluxrouter.ai/mcp-tools/",
      "headers": {
        "Authorization": "Bearer sk-YOUR-FLUX-KEY"
      }
    }
  }
}

mcp_servers:
  flux-tools:
    url: "https://api.fluxrouter.ai/mcp-tools/"
    headers:
      Authorization: "Bearer sk-YOUR-FLUX-KEY"

{
  "mcpServers": {
    "flux-tools": {
      "type": "streamableHttp",
      "url": "https://api.fluxrouter.ai/mcp-tools/",
      "headers": {
        "Authorization": "Bearer sk-YOUR-FLUX-KEY"
      }
    }
  }
}

curl https://api.fluxrouter.ai/v1/images/generations \
  -H "Authorization: Bearer sk-YOUR-FLUX-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-image",
    "prompt": "A watercolour fox asleep in a library",
    "max_price": 0.25
  }'

import base64
import requests

resp = requests.post(
    "https://api.fluxrouter.ai/v1/images/generations",
    headers={"Authorization": "Bearer sk-YOUR-FLUX-KEY"},
    json={
        "model": "flux-image",
        "prompt": "A watercolour fox asleep in a library",
        "max_price": 0.25,  # the most you will pay, in US dollars
    },
)
resp.raise_for_status()

image = resp.json()["data"][0]["b64_json"]
with open("fox.png", "wb") as f:
    f.write(base64.b64decode(image))

import { writeFile } from 'node:fs/promises';

const resp = await fetch('https://api.fluxrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk-YOUR-FLUX-KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'flux-image',
    prompt: 'A watercolour fox asleep in a library',
    max_price: 0.25, // the most you will pay, in US dollars
  }),
});
if (!resp.ok) throw new Error(await resp.text());

const { data } = await resp.json();
await writeFile('fox.png', Buffer.from(data[0].b64_json, 'base64'));

The response is { "created": ..., "data": [ { "b64_json": "..." } ] }. b64_json is the image, base64-encoded; decode it and save it as a file.

Ask for more than one image with n. Each image is billed.

Stream partial images#

Set "stream": true and the response becomes server-sent events:

1. Up to 3 image_generation.partial_image frames, each with a rough b64_json, if you set partial_images and the model supports it.
2. One image_generation.completed frame with the final data, shaped like the normal response.
3. data: [DONE].

Models without partial frames send only the completed frame, so one client works for every model. An error after the stream starts arrives as a frame with "type": "error". Streaming is for generation only, not edits.

Edit with reference images#

Send POST /v1/images/edits as a multipart form with a prompt and between one and 4 reference images in image[]. Edits always return exactly one image.

• Files can be PNG, JPEG or WebP, up to 10 MB each and 20 MB in total.
• Edits work on flux-image (the default when you leave model out) and flux-image-pro. Other models answer 400 edit_unsupported.
• There is no edit tool on the tools server, so edits are for your own code.

curl https://api.fluxrouter.ai/v1/images/edits \
  -H "Authorization: Bearer $FLUX_API_KEY" \
  -F model=flux-image \
  -F prompt="Give the fox a red scarf" \
  -F max_price=0.25 \
  -F "image[]=@fox.png"

import base64
import requests

with open("fox.png", "rb") as f:
    resp = requests.post(
        "https://api.fluxrouter.ai/v1/images/edits",
        headers={"Authorization": f"Bearer {FLUX_API_KEY}"},
        data={"model": "flux-image", "prompt": "Give the fox a red scarf", "max_price": "0.25"},
        files=[("image[]", ("fox.png", f, "image/png"))],
    )
resp.raise_for_status()
with open("fox-scarf.png", "wb") as out:
    out.write(base64.b64decode(resp.json()["data"][0]["b64_json"]))

An edit response also carries model and a usage object with the cost. For a loop that generates and then refines, see Generate, then refine an image.

Cap the price#

max_price is the most you will pay for the call, in US dollars. Flux checks the final price, including any pay-as-you-go markup, before it charges. If the price is higher, the call answers 402 price_exceeds_max_price: you get no image and you are not charged.

Sizes and quality#

• size defaults to 1024x1024. Most models make their own fixed size and ignore it.
• quality changes the price, not the request shape.
• response_format defaults to b64_json.

What it costs#

Images are billed per image: from $0.01 per image. The price per model is in the table above, and max_price caps what any one call can cost. An edit response says what it cost in usage.cost; every image call is itemised on your usage page and lands on the same bill as your other usage. See How billing works.

Images are a paid ability. On the Free plan a call answers 402 premium_locked and nothing is made or charged. Image calls do not count against the shared per-minute limit for audio and search.

If something goes wrong#

Every image error, with its fix, is on Image problems. The exact request and response fields are in the images reference.