Name: FLUX.2 [flex] Image Generation & Editing API
Brand: magicapi
SKU: api-magicapi-image-generation-max-quality-black-forest-labs-flux-2-flex
Availability: InStock
Author: API Market

Shashank Agarwal

# 🖼️ Max-Quality Image Generation & Editing API (FLUX.2 [flex])

## Overview
This API runs FLUX.2 [flex] from Black Forest Labs, a max-quality image generation and editing model with support for up to 10 reference images. Send a text prompt to generate an image, or add input images and describe what to make from them. Each request returns one image.

## Features
- Text-to-image generation from a prompt
- Image-to-image generation and editing with up to 10 input images (`input_images`)
- 9 preset aspect ratios, `match_input_image` to match the first input image, or `custom` with your own `width` and `height` (256 to 2048 px)
- Output resolution of 0.5, 1 (default), 2 or 4 megapixels (`resolution`), or `match_input_image` to match the input image's resolution
- `steps` and `guidance` to control generation, and `prompt_upsampling` (on by default) to expand the prompt automatically
- `safety_tolerance` from 1 (most strict) to 5 (most permissive)
- `seed` for reproducible generation
- Output as webp (default), jpg or png, with adjustable quality

## Use Cases
1. **Product and marketing visuals**: generate scenes, ads and social images from a written description.
2. **Edits guided by references**: pass a photo and describe the change, such as a new background or color.
3. **Combining many references**: bring products, people and styles from up to 10 images into one image.
4. **Exact dimensions**: set `aspect_ratio` to `custom` with a `width` and `height` for a fixed layout slot.
5. **Repeatable results**: fix the `seed` to reproduce an image while you adjust other settings.

## Visual Examples
### Text-to-image
**Prompt:** "A bookshop window display at night with a hand-painted sign that reads 'api.market books', warm interior light, rain on the glass"

All other inputs were left at their defaults (`aspect_ratio` "1:1", `resolution` "1 MP", `output_format` "webp").

![A bookshop window display at night with a hand-painted sign that reads api.market books, warm light and rain on the glass](https://blog.api.market/wp-content/uploads/2026/10/flux-2-flex-output-api-market.webp)

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.075 per API unit.
- **1 API unit** = 1 megapixel of output image.
- Input image megapixels are billed the same way, at the same $0.075 per megapixel.
- The megapixels of the output image and every input image are added together and rounded up to a whole unit per request.
- Text-to-image (no input images) by `resolution` setting:
  - "0.5 MP": 0.5 units, billed as 1 unit = $0.075
  - "1 MP" (default): 1 unit = $0.075
  - "2 MP": 2 units = $0.15
  - "4 MP": 4 units = $0.30
- **Worked example (editing)**: a 1 megapixel output with two 1 megapixel input images is 1 + 1 + 1 = 3 units = $0.225.
- Failed or cancelled predictions are not billed.
- GET requests to check prediction status are free and don't count toward API unit usage.
- No monthly subscription fee.

## API Documentation

### Base URL
All API requests should be made to: `https://prod.api.market/api/v1/magicapi/image-generation-max-quality-black-forest-labs-flux-2-flex`

### Authentication
Include your api.market API key in the request header:

```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:

1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (the image URL is in `output`), `failed` or `canceled` (see `error`).

Suggested client settings:
- Poll every 1 second
- Give up after 600 seconds (10 minutes)

### Endpoints
#### `POST /api/v1/magicapi/image-generation-max-quality-black-forest-labs-flux-2-flex/predictions`
Create a prediction.

**Request Example:**

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/image-generation-max-quality-black-forest-labs-flux-2-flex/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "dbeea265fe7b67a03086ed29ddc54b55cc5387aeba8d84f9e80adbf5698a0f67",
    "input": {
      "prompt": "A bookshop window display at night with a hand-painted sign that reads '\''api.market books'\'', warm interior light, rain on the glass"
    }
  }'
```

**Response (201 Created):**
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "dbeea265fe7b67a03086ed29ddc54b55cc5387aeba8d84f9e80adbf5698a0f67",
  "status": "starting",
  "created_at": "2026-10-12T10:37:05.471Z"
}
```

#### `GET /api/v1/magicapi/image-generation-max-quality-black-forest-labs-flux-2-flex/predictions/{id}`
Check prediction status and get the result.

**Request Example:**
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/image-generation-max-quality-black-forest-labs-flux-2-flex/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example (200 OK):**
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/flux-2-flex-output-api-market.webp",
  "error": null,
  "created_at": "2026-10-12T10:37:05.471Z",
  "started_at": "2026-10-12T10:37:06.000Z",
  "completed_at": "2026-10-12T10:37:16.000Z"
}
```

`output` is a single image URL.

### Status Codes
- **201 Created**: prediction created (POST). This is the normal success response.
- **200 OK**: prediction found (GET). Check `status` for progress.
- **400 Bad Request**: invalid input parameters or malformed request
- **401 Unauthorized**: missing or invalid API key
- **404 Not Found**: prediction not found
- **429 Too Many Requests**: rate limit exceeded
- **500 Internal Server Error**: server-side error

### Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Implementation Guide

### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/image-generation-max-quality-black-forest-labs-flux-2-flex";

async function createAndWaitForPrediction(inputData) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({
      version: "dbeea265fe7b67a03086ed29ddc54b55cc5387aeba8d84f9e80adbf5698a0f67",
      input: inputData
    })
  });

  // 201 Created is the normal success response
  if (!response.ok) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return await pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000;
  const POLL_INTERVAL = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  prompt: "A bookshop window display at night with a hand-painted sign that reads 'api.market books', warm interior light, rain on the glass"
}).then((imageUrl) => console.log(imageUrl));
```

### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/image-generation-max-quality-black-forest-labs-flux-2-flex"

def create_and_wait_for_prediction(input_data):
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY,
    }
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "dbeea265fe7b67a03086ed29ddc54b55cc5387aeba8d84f9e80adbf5698a0f67", "input": input_data},
    )
    # 201 Created is the normal success response
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()
        if prediction["status"] == "succeeded":
            return prediction["output"]
        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")

image_url = create_and_wait_for_prediction({
    "prompt": "A bookshop window display at night with a hand-painted sign that reads 'api.market books', warm interior light, rain on the glass"
})
print(image_url)
```

### cURL
```bash
# Step 1: Create a prediction (returns 201 Created with an id)
curl -X POST "https://prod.api.market/api/v1/magicapi/image-generation-max-quality-black-forest-labs-flux-2-flex/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "dbeea265fe7b67a03086ed29ddc54b55cc5387aeba8d84f9e80adbf5698a0f67",
    "input": {
      "prompt": "A bookshop window display at night with a hand-painted sign that reads '\''api.market books'\'', warm interior light, rain on the glass"
    }
  }'

# Step 2: Check prediction status (replace {id} with the id from step 1)
curl -X GET "https://prod.api.market/api/v1/magicapi/image-generation-max-quality-black-forest-labs-flux-2-flex/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

## Input Parameters
| Parameter | Type | Default | Allowed Values | Required | Description |
|-----------|------|---------|----------------|----------|-------------|
| prompt | string | none | Any text | Yes | Text prompt for image generation. |
| input_images | array of URLs | [] | Up to 10 image URLs (jpeg, png, gif or webp) | No | Input images for image-to-image generation. Their megapixels are billed (see Pricing). |
| aspect_ratio | string | "1:1" | "match_input_image", "custom", "1:1", "16:9", "3:2", "2:3", "4:5", "5:4", "9:16", "3:4", "4:3" | No | Aspect ratio for the generated image. "match_input_image" matches the first input image's aspect ratio. "custom" uses `width` and `height`. |
| resolution | string | "1 MP" | "match_input_image", "0.5 MP", "1 MP", "2 MP", "4 MP" | No | Resolution in megapixels. Up to 4 MP is possible, but 2 MP or below is recommended. The maximum image size is 2048x2048, so high resolutions may not be reached when the aspect ratio is not 1:1. Not used when `aspect_ratio` is "custom". With `aspect_ratio` "match_input_image", use "match_input_image" to match the input image's resolution (clamped to 0.5 to 4 MP). |
| width | integer | null | 256 to 2048 | No | Width of the generated image. Only used when `aspect_ratio` is "custom". Must be a multiple of 16 (other values are rounded to the nearest multiple of 16). |
| height | integer | null | 256 to 2048 | No | Height of the generated image. Only used when `aspect_ratio` is "custom". Must be a multiple of 16 (other values are rounded to the nearest multiple of 16). |
| safety_tolerance | integer | 2 | 1 to 5 | No | Safety tolerance, 1 is most strict and 5 is most permissive. |
| seed | integer | none | Any integer | No | Random seed. Set for reproducible generation. |
| prompt_upsampling | boolean | true | true, false | No | Automatically modify the prompt for more creative generation. |
| steps | integer | 30 | 1 to 50 | No | Number of inference steps. |
| guidance | number | 4.5 | 1.5 to 10 | No | Guidance scale. Controls how closely the output follows the prompt. |
| output_format | string | "webp" | "webp", "jpg", "png" | No | Format of the output image. |
| output_quality | integer | 80 | 0 to 100 | No | Quality when saving the output image. 100 is best quality, 0 is lowest. Not relevant for png outputs. |

## FAQ
- **How do I authenticate with the API?**
  Send your api.market API key in the `x-api-market-key` request header.

- **Why does the POST return 201 instead of 200?**
  201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until the status is `succeeded`, `failed` or `canceled`.

- **How many reference images can I use?**
  Up to 10 in `input_images` (jpeg, png, gif or webp).

- **Do input images cost extra?**
  Yes. Input image megapixels are added to the output megapixels and billed at the same $0.075 per megapixel, rounded up to a whole unit per request.

- **Do I get charged for failed or cancelled requests?**
  No, failed or cancelled predictions are not billed.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Generate and edit images with FLUX.2 [flex] by Black Forest Labs, with up to 10 reference images. $0.075 per megapixel.