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

Shashank Agarwal

# 🖼️ Image Generation & Editing API (FLUX.2 [dev])

## Overview
This API runs FLUX.2 [dev] from Black Forest Labs, an image generation and editing model with support for reference images. Send a text prompt to generate an image, or add up to 4 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 4 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 1440 px)
- `go_fast` mode with additional optimizations, on by default (and billed at the lower rate)
- `seed` for reproducible generation
- Output as webp (default), jpg or png, with adjustable quality
- Safety checker on by default (`disable_safety_checker` turns it off)

## Use Cases
1. **Marketing and product 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 color or background.
3. **Combining references**: use up to 4 input images to bring a product, a person or a style 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 cozy reading nook by a large window overlooking a rainy city at dusk, warm lamp light, a laptop on the table showing a dashboard titled 'api.market'"

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

![Cozy reading nook by a rainy city window at dusk with a laptop showing an api.market dashboard](https://blog.api.market/wp-content/uploads/2026/10/flux-2-dev-output-api-market.webp)

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.015 per API unit.
- **1 API unit** = 1 megapixel (a 1024x1024 image counts as 1 megapixel). The output image and every input image are counted.
- **`go_fast: true` (the default)**: 1 unit per megapixel = **$0.015 per megapixel**.
- **`go_fast: false`**: 1.167 units per megapixel, rounded up to whole units per request. A 1 megapixel image with `go_fast` off bills 2 units ($0.03).
- For example, a 1 megapixel edit of a 1 megapixel input image bills 2 units ($0.03) with `go_fast` on.
- 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/quality-image-generation-editing-black-forest-labs-flux-2-dev`

### 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/quality-image-generation-editing-black-forest-labs-flux-2-dev/predictions`
Create a prediction.

**Request Example:**

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/quality-image-generation-editing-black-forest-labs-flux-2-dev/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "7bba46bdde863cfd7aaee87649a5aa49f39f368495dbea500998d1fcbb262050",
    "input": {
      "prompt": "A cozy reading nook by a large window overlooking a rainy city at dusk, warm lamp light, a laptop on the table showing a dashboard titled '\''api.market'\''"
    }
  }'
```

**Response (201 Created):**
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "7bba46bdde863cfd7aaee87649a5aa49f39f368495dbea500998d1fcbb262050",
  "status": "starting",
  "created_at": "2026-10-11T19:02:25.688Z"
}
```

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

**Request Example:**
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/quality-image-generation-editing-black-forest-labs-flux-2-dev/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-dev-output-api-market.webp",
  "error": null,
  "created_at": "2026-10-11T19:02:25.688Z",
  "started_at": "2026-10-11T19:02:26.000Z",
  "completed_at": "2026-10-11T19:02:35.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/quality-image-generation-editing-black-forest-labs-flux-2-dev";

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: "7bba46bdde863cfd7aaee87649a5aa49f39f368495dbea500998d1fcbb262050",
      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 cozy reading nook by a large window overlooking a rainy city at dusk, warm lamp light, a laptop on the table showing a dashboard titled 'api.market'"
}).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/quality-image-generation-editing-black-forest-labs-flux-2-dev"

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": "7bba46bdde863cfd7aaee87649a5aa49f39f368495dbea500998d1fcbb262050",
            "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 cozy reading nook by a large window overlooking a rainy city at dusk, warm lamp light, a laptop on the table showing a dashboard titled 'api.market'"
})
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/quality-image-generation-editing-black-forest-labs-flux-2-dev/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "7bba46bdde863cfd7aaee87649a5aa49f39f368495dbea500998d1fcbb262050",
    "input": {
      "prompt": "A cozy reading nook by a large window overlooking a rainy city at dusk, warm lamp light, a laptop on the table showing a dashboard titled '\''api.market'\''"
    }
  }'

# Step 2: Check prediction status (replace {id} with the id from step 1)
curl -X GET "https://prod.api.market/api/v1/magicapi/quality-image-generation-editing-black-forest-labs-flux-2-dev/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 description of the image to generate. |
| input_images | array of URLs | none | Up to 4 image URLs (jpeg, png, gif or webp) | No | Input images for image-to-image generation. |
| go_fast | boolean | true | true, false | No | Run faster predictions with additional optimizations. Also sets the price per megapixel (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`. |
| width | integer | null | 256 to 1440 | No | Width of the generated image in text-to-image mode. Only used when `aspect_ratio` is "custom". Must be a multiple of 32 (other values are rounded to the nearest multiple of 32). |
| height | integer | null | 256 to 1440 | No | Height of the generated image in text-to-image mode. Only used when `aspect_ratio` is "custom". Must be a multiple of 32 (other values are rounded to the nearest multiple of 32). |
| seed | integer | null | Any integer | No | Random seed. Set for reproducible generation. |
| 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. |
| disable_safety_checker | boolean | false | true, false | No | Disable the safety checker for generated images. |

## 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 do I edit an existing image?**
  Put the image URL in `input_images` (up to 4) and describe the result in `prompt`. Set `aspect_ratio` to "match_input_image" to keep the original proportions.

- **Does `go_fast` change the price?**
  Yes. With `go_fast` on (the default) one megapixel is 1 unit ($0.015). With it off, one megapixel is 1.167 units, and the request total is rounded up to whole units, so a 1 megapixel image costs 2 units ($0.03).

- **Do input images cost extra?**
  Yes. Input image megapixels are added to the output megapixels and billed at the same rate.

- **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 [dev] by Black Forest Labs. Up to 4 reference images, custom sizes, from $0.015 per megapixel.