Name: Text-to-Image and Image-to-Image API (Flux Dev)
Brand: magicapi
SKU: api-magicapi-text-to-image-generator-black-forest-labs-flux-dev
Availability: InStock
Author: API Market

Shashank Agarwal

# 🖼️ Text-to-Image and Image-to-Image Generator API (Flux Dev)

## Overview

The Flux Dev API generates images from text descriptions and can also transform an input image guided by your prompt. It runs Flux Dev from Black Forest Labs, a 12 billion parameter rectified flow transformer, and outputs images of about 1 megapixel or smaller.

## Features

- **Image Generation up to about 1 Megapixel:** `megapixels` accepts `"1"` (default; 1024x1024 at 1:1 in our test) or `"0.25"`.
- **Fast and Accurate:** Powered by a 12-billion parameter rectified flow transformer for quick and precise results.
- **Two Modes:** Text-to-image, or image-to-image by passing an `image` URL and tuning `prompt_strength` (useful for restyling an existing image).
- **Customizable Settings:** Control aspects like seed, guidance, image quality, aspect ratio, and more.
- **Asynchronous Processing:** Efficient and fast prediction processing with easy-to-poll endpoints.

## Use Cases

### 1. E-commerce Product Visualization
Generate realistic product images from textual descriptions for online stores, enhancing customer experience and reducing the need for extensive photo shoots.

### 2. Creative Content Generation
Artists and designers can generate concept art or illustrations from simple text prompts, speeding up the creative process and allowing for more experimentation.

### 3. Advertising and Marketing
Create visually captivating ad visuals from text descriptions to catch the audience's attention and convey the message effectively.

### 4. Social Media Content
Produce engaging and visually appealing social media posts by generating images based on trending topics or user-generated content.

### 5. Video Game Development
Generate high-quality game assets and scenery from descriptive text, saving time and resources in the game development pipeline.

## Visual Examples

### Example Input

```json
{
  "input": {
    "prompt": "black forest gateau cake spelling out the words \"FLUX DEV\", tasty, food photography, dynamic shot",
    "num_outputs": 2,
    "aspect_ratio": "1:1",
    "output_format": "webp"
  }
}
```

### Example Output

![Example output from Text-to-Image and Image-to-Image Generator API (Flux Dev)](https://blog.api.market/wp-content/uploads/2026/09/flux-dev-output-api-market.webp)

The request asked for 2 images; the first is shown.

This exact request was run through api.market and billed 2 API units ($0.064).
## Pricing

- **Pay As You Go (PAYG) pricing** - you only pay for what you use.
- **Price: $0.032 per API unit.**
- 1 API unit = 1 output image; a request that returns several images is billed for each one.
- Failed or cancelled predictions are not billed.
- GET requests to check prediction status (GET /api/v1/magicapi/text-to-image-generator-black-forest-labs-flux-dev/predictions/{id}) 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-generator-black-forest-labs-flux-dev`

### Authentication
Authentication is handled via API key. Include your API key in the request header:
```plaintext
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing

**IMPORTANT**: This API uses asynchronous processing for predictions. The typical flow is:

1. Submit a prediction request to the **POST** endpoint
2. Receive a prediction ID in the response
3. Poll the **GET** endpoint with the prediction ID to check status
4. Continue polling until the prediction is complete

The processing time varies depending on the complexity of the request. Your code should implement:
- A polling interval of 1 second between status checks
- A maximum timeout of 600 seconds (10 minutes)
- Status checking logic that continues while status is "starting" or "processing"
- Result handling when status becomes "succeeded"
- Error handling when status becomes "failed" or timeout is reached

### Input Parameters
| Name | Type | Required | Default | Allowed values and notes |
|---|---|---|---|---|
| `prompt` | string | Yes | none | Prompt for the generated image |
| `aspect_ratio` | string | No | `"1:1"` | `1:1`, `16:9`, `21:9`, `3:2`, `2:3`, `4:5`, `5:4`, `3:4`, `4:3`, `9:16`, `9:21`. With `image`, the output matches the input image's aspect ratio |
| `image` | string (URI) | No | none | Input image for image-to-image mode |
| `prompt_strength` | number | No | `0.8` | 0 to 1; 1.0 fully replaces the input image's information |
| `num_outputs` | integer | No | `1` | 1 to 4; each image is billed |
| `num_inference_steps` | integer | No | `28` | 1 to 50; 28 to 50 recommended, fewer is faster but lower quality |
| `guidance` | number | No | `3` | 0 to 10 |
| `seed` | integer | No | none | Random seed; reproducible only with `go_fast` set to `false` |
| `output_format` | string | No | `"webp"` | `webp`, `jpg`, `png` |
| `output_quality` | integer | No | `80` | 0 to 100; not used for png |
| `disable_safety_checker` | boolean | No | `false` | Disable the safety checker |
| `go_fast` | boolean | No | `true` | fp8 optimized model; outputs are not deterministic when on |
| `megapixels` | string | No | `"1"` | `"1"` or `"0.25"` |

### Endpoints

- **POST /predictions**
  Submit a prediction request.

  Request:
  ```json
  {
    "version": "6e4a938f85952bdabcc15aa329178c4d681c52bf25a0342403287dc26944661d",
    "input": {
      "prompt": "black forest gateau cake spelling out the words \"FLUX DEV\", tasty, food photography, dynamic shot",
      "go_fast": true,
      "guidance": 3.5,
      "megapixels": "1",
      "num_outputs": 1,
      "aspect_ratio": "1:1",
      "output_format": "webp",
      "output_quality": 80,
      "prompt_strength": 0.8,
      "num_inference_steps": 28
    }
  }
  ```

  Example with curl:
  ```bash
  curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-image-generator-black-forest-labs-flux-dev/predictions" \
    -H "Content-Type: application/json" \
    -H "x-api-market-key: YOUR_API_MARKET_KEY" \
    -d '{
      "version": "6e4a938f85952bdabcc15aa329178c4d681c52bf25a0342403287dc26944661d",
      "input": {
        "prompt": "black forest gateau cake spelling out the words \"FLUX DEV\", tasty, food photography, dynamic shot"
      }
    }'
  ```

- **GET /predictions/{id}**
  Check the status of a prediction.

  Example with curl:
  ```bash
  curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-image-generator-black-forest-labs-flux-dev/predictions/abcd1234" \
    -H "x-api-market-key: YOUR_API_MARKET_KEY"
  ```

## Status Codes

- **200 OK**: Request successful
- **201 Created**: Resource successfully created
- **400 Bad Request**: Invalid input parameters or malformed request
- **401 Unauthorized**: Missing or invalid API key
- **403 Forbidden**: Valid API key but insufficient permissions
- **404 Not Found**: Resource not found
- **429 Too Many Requests**: Rate limit exceeded
- **500 Internal Server Error**: Server-side error
- **503 Service Unavailable**: Service temporarily unavailable

For each status code, handle responses appropriately within your application logic.

## Rate Limits

API requests may be subject to rate limits to ensure fair usage. If you exceed these limits, you may receive a **429 Too Many Requests** response. Implement exponential backoff strategies for handling rate limit errors.

## Error Handling

Implement robust error handling to manage various error responses:
- **Invalid Parameter**: Check for required parameters.
- **Invalid API Key**: Ensure correct API key inclusion.
- **Rate Limit Exceeded**: Implement retry strategies with exponential backoff.
- **Server Errors**: Retry requests after some time, and report persistent issues.

Example JSON error response:
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'prompt' is required",
    "status": 400
  }
}
```

## Implementation Guide

### Example Code

```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-to-image-generator-black-forest-labs-flux-dev";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-market-key": apiKey
      },
      body: JSON.stringify({ version: "6e4a938f85952bdabcc15aa329178c4d681c52bf25a0342403287dc26944661d", input: inputData })
    });
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }
    
    const prediction = await response.json();
    const predictionId = prediction.id;
    
    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second between checks
  
  const startTime = Date.now();
  
  while (Date.now() - startTime < MAX_TIMEOUT) {
    // Check prediction status
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-api-market-key": apiKey
      }
    });
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }
    
    const prediction = await response.json();
    
    // Check status and return if completed
    if (prediction.status === "succeeded") {
      return prediction.output;
    }
    
    // Handle failure
    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }
    
    // Wait before next poll
    await delay(POLL_INTERVAL);
  }
  
  throw new Error("Prediction timed out after 10 minutes");
}
```

```python
# Python example with proper polling and timeout
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/text-to-image-generator-black-forest-labs-flux-dev"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }
    
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "6e4a938f85952bdabcc15aa329178c4d681c52bf25a0342403287dc26944661d", "input": input_data}
    )
    
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")
    
    prediction = response.json()
    prediction_id = prediction["id"]
    
    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second between checks
    
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()
    
    while time.time() - start_time < MAX_TIMEOUT:
        # Check prediction status
        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()
        
        # Check status and return if completed
        if prediction["status"] == "succeeded":
            return prediction["output"]
        
        # Handle failure
        if prediction["status"] in ("failed", "canceled"):
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")
        
        # Wait before next poll
        time.sleep(POLL_INTERVAL)
    
    raise Exception("Prediction timed out after 10 minutes")
```

```bash
# cURL example
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-image-generator-black-forest-labs-flux-dev/predictions" -H "Content-Type: application/json" -H "x-api-market-key: YOUR_API_MARKET_KEY" -d '{
    "version": "6e4a938f85952bdabcc15aa329178c4d681c52bf25a0342403287dc26944661d",
    "input": {
      "prompt": "black forest gateau cake spelling out the words \"FLUX DEV\", tasty, food photography, dynamic shot"
    }
  }'

# Response will contain a prediction ID like:
# {"id": "abcd1234", "status": "starting"}

# Step 2: Check prediction status (replace abcd1234 with the actual ID)
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-image-generator-black-forest-labs-flux-dev/predictions/abcd1234" -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Note: You need to repeatedly poll this endpoint manually until status is "succeeded"
```

### Performance Optimization

- `go_fast` is `true` by default for faster predictions; set it to `false` to run in original bf16 precision and get reproducible outputs with a fixed `seed`.
- Utilize the "num_outputs" parameter to generate multiple images in a single request, reducing the overhead of multiple API calls.
- Lower `num_inference_steps` (default 28, range 1 to 50) or set `megapixels` to `"0.25"` for faster, lower-detail results. `output_quality` only changes file compression.
  
## FAQ

1. **How do I get my API key?**
   Sign up on api.market and copy your key from the API Keys page in your account.

2. **Can I generate multiple images from a single prompt?**
   Yes, use the "num_outputs" parameter to specify how many images you want to generate from a single request.

3. **What formats are supported for the output images?**
   `webp` (default), `jpg` and `png`, set with `output_format`.

4. **Can I control the aspect ratio of the generated images?**
   Yes, you can specify the aspect ratio using the "aspect_ratio" parameter.

5. **How do I check the status of a prediction?**
   Use the GET /predictions/{id} endpoint with your prediction ID to check the status of your prediction.

## 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 stunning images from text descriptions with the high-accuracy and speedy Flux Dev API, powered by a 12-billion parameter model.