Name: FLUX 3 Text-to-Image & Image Editing API
Brand: magicapi
SKU: api-magicapi-text-to-image-image-editing-api-black-forest-labs-flux-3-image
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎨 Text-to-Image & Image Editing API (FLUX 3)

## Overview
This API runs FLUX 3, the text-to-image and image-editing model from Black Forest Labs. Send a text prompt to generate a new image, or send up to 10 reference images with a prompt that describes the edit. Each request returns one image.

## Features
- Generate an image from a text prompt
- Edit or draw from up to 10 reference images (`images`); when images are present the request runs as an edit
- Five output resolutions: `768sq`, `1k` (default), `1.5k`, `2k` and `4k`
- 15 fixed aspect ratios plus `auto`, which picks the ratio from the prompt and the first reference image
- Optional grounding (on by default): the model researches the prompt with web search and image search before generating
- Output as webp (default), jpg or png, with adjustable quality
- Adjustable moderation tolerance from 0 (strictest) to 4 (most permissive)

## Use Cases
1. **Product and marketing images**: describe a product shot, scene or ad visual and get a finished image.
2. **Editing existing images**: pass your photos as references and describe the change you want.
3. **Combining references**: draw from several reference images (up to 10) in one request.
4. **Prompts about real things**: with grounding on, the model looks up the subject on the web before generating.
5. **Different placements**: pick the aspect ratio and resolution that fit a banner, a social post or a print layout.

## Visual Examples
### Text-to-image
**Prompt:** "A minimalist product photo of a white ceramic coffee mug on a marble counter in soft morning sunlight, the mug printed with the words 'api.market' in clean black type"

All other inputs were left at their defaults (`resolution` "1k", `aspect_ratio` "auto", `grounding` true, `output_format` "webp").

![White ceramic coffee mug printed with api.market on a marble counter in morning sunlight](https://blog.api.market/wp-content/uploads/2026/10/flux-3-image-output-api-market.webp)

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.005 per API unit.
- **Billing unit**: each output image is billed a whole number of units that depends on the `resolution` you request:
  - `768sq`: 6 units per image ($0.03)
  - `1k`: 6 units per image ($0.03)
  - `1.5k`: 9 units per image ($0.045)
  - `2k`: 13 units per image ($0.065)
  - `4k`: 76 units per image ($0.38)
- A request that does not set `resolution` uses the default `1k` and bills 6 units ($0.03).
- 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/text-to-image-image-editing-api-black-forest-labs-flux-3-image`

### 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/text-to-image-image-editing-api-black-forest-labs-flux-3-image/predictions`
Create a prediction.

**Request Example:**

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-image-image-editing-api-black-forest-labs-flux-3-image/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ec84b8fbf178998c3d5a2c3a32b4fdd850caac711a5145a1ede36e307ade7ca9",
    "input": {
      "prompt": "A minimalist product photo of a white ceramic coffee mug on a marble counter in soft morning sunlight, the mug printed with the words '\''api.market'\'' in clean black type"
    }
  }'
```

**Response (201 Created):**
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "ec84b8fbf178998c3d5a2c3a32b4fdd850caac711a5145a1ede36e307ade7ca9",
  "status": "starting",
  "created_at": "2026-10-11T19:12:52.095Z"
}
```

#### `GET /api/v1/magicapi/text-to-image-image-editing-api-black-forest-labs-flux-3-image/predictions/{id}`
Check prediction status and get the result.

**Request Example:**
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-image-image-editing-api-black-forest-labs-flux-3-image/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-3-image-output-api-market.webp",
  "error": null,
  "created_at": "2026-10-11T19:12:52.095Z",
  "started_at": "2026-10-11T19:12:53.000Z",
  "completed_at": "2026-10-11T19:13:05.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/text-to-image-image-editing-api-black-forest-labs-flux-3-image";

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: "ec84b8fbf178998c3d5a2c3a32b4fdd850caac711a5145a1ede36e307ade7ca9",
      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 minimalist product photo of a white ceramic coffee mug on a marble counter in soft morning sunlight, the mug printed with the words 'api.market' in clean black type"
}).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/text-to-image-image-editing-api-black-forest-labs-flux-3-image"

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": "ec84b8fbf178998c3d5a2c3a32b4fdd850caac711a5145a1ede36e307ade7ca9",
            "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 minimalist product photo of a white ceramic coffee mug on a marble counter in soft morning sunlight, the mug printed with the words 'api.market' in clean black type"
})
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/text-to-image-image-editing-api-black-forest-labs-flux-3-image/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ec84b8fbf178998c3d5a2c3a32b4fdd850caac711a5145a1ede36e307ade7ca9",
    "input": {
      "prompt": "A minimalist product photo of a white ceramic coffee mug on a marble counter in soft morning sunlight, the mug printed with the words '\''api.market'\'' in clean black type"
    }
  }'

# Step 2: Check prediction status (replace {id} with the id from step 1)
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-image-image-editing-api-black-forest-labs-flux-3-image/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, or of the edit to apply to the reference images. |
| images | array of URLs | [] | Up to 10 image URLs (jpeg, png, gif or webp), each at least 256x256 px and at most 16 MP | No | Reference images the prompt edits or draws from. When present, the request runs as an edit and the first image drives `auto` aspect ratio. |
| aspect_ratio | string | "auto" | "auto", "21:9", "2:1", "16:9", "3:2", "7:5", "4:3", "5:4", "1:1", "4:5", "3:4", "5:7", "2:3", "9:16", "1:2", "9:21" | No | Aspect ratio of the generated image. "auto" picks the ratio from the prompt and the first reference image. |
| resolution | string | "1k" | "768sq", "1k", "1.5k", "2k", "4k" | No | Resolution of the output image. Input images are resized to the closest bin, up to 2k. Sets the price per image. |
| grounding | boolean | true | true, false | No | Let the model research the prompt with web search and image search before generating. |
| safety_tolerance | integer | 2 | 0 to 4 | No | Moderation tolerance for inputs and outputs. 0 is the strictest, 4 is the most permissive. |
| 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 do I edit an existing image?**
  Put one or more image URLs (up to 10) in `images` and describe the change in `prompt`.

- **How much does one image cost?**
  It depends on `resolution`: $0.03 (768sq), $0.03 (1k, the default), $0.045 (1.5k), $0.065 (2k) or $0.38 (4k).

- **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 images from text or edit up to 10 reference images with FLUX 3 by Black Forest Labs. Five resolutions up to 4k, pay per image.