Name: FLUX.1 Depth [dev] Depth-Guided Image Generation API
Brand: magicapi
SKU: api-magicapi-depth-aware-image-editing-black-forest-labs-flux-depth-dev
Availability: InStock
Author: API Market

Shashank Agarwal

# 🖼️ Depth-Guided Image Generation API (FLUX.1 Depth [dev])

## Overview
This API runs FLUX.1 Depth [dev] from Black Forest Labs, an open-weight depth-aware image generation model. Send a control image and a prompt: a depth map is generated from the control image automatically, and the model creates a new image that follows the prompt while keeping the spatial relationships of the original scene.

## Features
- Depth-guided generation from a `control_image` and a `prompt` (both required)
- The depth map is generated for you; no separate depth model needed
- 1 to 4 images per request (`num_outputs`)
- Output size of about 1 megapixel (default), 0.25 megapixel, or `match_input` to match the input size (up to 1440x1440 pixels)
- `num_inference_steps` and `guidance` to control generation
- `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. **Restyling a scene**: keep the layout and poses of a photo and change the material, style or setting, such as turning a person into a statue.
2. **Product and interior variations**: keep the shape and placement of objects while changing colors, textures or surroundings.
3. **Concept art from references**: use a photo or a rough render as the structure and describe the look you want.
4. **Consistent compositions**: generate several variations (up to 4 per request) that share the same spatial layout.

## Visual Examples
### Depth-guided generation
**Prompt:** "A bronze statue of a woman in a hooded coat standing in a museum hall, soft gallery lighting"

All other inputs were left at their defaults (`megapixels` "1", `num_outputs` 1, `output_format` "webp").

**Control image:** [View the control image](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp)

**Output:**

![A bronze statue of a woman in a hooded coat standing in a museum hall, following the layout of the control image](https://blog.api.market/wp-content/uploads/2026/10/flux-depth-dev-output-api-market.webp)

## 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 is billed for every image it returns (`num_outputs`):
  - 1 image (default): 1 unit = $0.032
  - 2 images: 2 units = $0.064
  - 3 images: 3 units = $0.096
  - 4 images: 4 units = $0.128
- 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/depth-aware-image-editing-black-forest-labs-flux-depth-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 URLs are 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/depth-aware-image-editing-black-forest-labs-flux-depth-dev/predictions`
Create a prediction.

**Request Example:**

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/depth-aware-image-editing-black-forest-labs-flux-depth-dev/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "fc4f1401056237174d207056c49cd2afd44ede232ba286a3d40eb6376b726600",
    "input": {
      "prompt": "A bronze statue of a woman in a hooded coat standing in a museum hall, soft gallery lighting",
      "control_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp"
    }
  }'
```

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

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

**Request Example:**
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/depth-aware-image-editing-black-forest-labs-flux-depth-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-depth-dev-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 an array of image URLs, one per image requested with `num_outputs`.

### 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/depth-aware-image-editing-black-forest-labs-flux-depth-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: "fc4f1401056237174d207056c49cd2afd44ede232ba286a3d40eb6376b726600",
      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 bronze statue of a woman in a hooded coat standing in a museum hall, soft gallery lighting",
  control_image: "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp"
}).then((imageUrls) => console.log(imageUrls));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/depth-aware-image-editing-black-forest-labs-flux-depth-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": "fc4f1401056237174d207056c49cd2afd44ede232ba286a3d40eb6376b726600", "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_urls = create_and_wait_for_prediction({
    "prompt": "A bronze statue of a woman in a hooded coat standing in a museum hall, soft gallery lighting",
    "control_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp"
})
print(image_urls)
```

### cURL
```bash
# Step 1: Create a prediction (returns 201 Created with an id)
curl -X POST "https://prod.api.market/api/v1/magicapi/depth-aware-image-editing-black-forest-labs-flux-depth-dev/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "fc4f1401056237174d207056c49cd2afd44ede232ba286a3d40eb6376b726600",
    "input": {
      "prompt": "A bronze statue of a woman in a hooded coat standing in a museum hall, soft gallery lighting",
      "control_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp"
    }
  }'

# Step 2: Check prediction status (replace {id} with the id from step 1)
curl -X GET "https://prod.api.market/api/v1/magicapi/depth-aware-image-editing-black-forest-labs-flux-depth-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 | Prompt for the generated image. |
| control_image | string (URL) | none | Image URL | Yes | Image used to control the generation. The depth map is generated automatically. |
| num_outputs | integer | 1 | 1 to 4 | No | Number of images to generate. Each image is billed (see Pricing). |
| num_inference_steps | integer | 28 | 1 to 50 | No | Number of denoising steps. Recommended range is 28 to 50; fewer steps are faster but lower quality. |
| guidance | number | 10 | 0 to 100 | No | Guidance for the generated image. |
| seed | integer | none | Any integer | No | Random seed. Set for reproducible generation. |
| output_format | string | "webp" | "webp", "jpg", "png" | No | Format of the output images. |
| output_quality | integer | 80 | 0 to 100 | No | Quality when saving the output images. 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. |
| megapixels | string | "1" | "1", "0.25", "match_input" | No | Approximate number of megapixels for the generated image. "match_input" matches the size of the input, with an upper limit of 1440x1440 pixels. |

## 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`.

- **Do I need to send a depth map?**
  No. Send a normal image in `control_image`; the depth map is generated from it automatically.

- **How is a request with several images billed?**
  Each output image is 1 unit ($0.032), so `num_outputs` 4 costs $0.128.

- **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 that keep the spatial layout of a control image with FLUX.1 Depth [dev] by Black Forest Labs. $0.032 per image.