Name: FLUX.1 Kontext Max Multi-Image Combine API
Brand: magicapi
SKU: api-magicapi-multi-image-processing-api-flux-kontext-apps-multi-image-list
Availability: InStock
Author: API Market

Shashank Agarwal

# 🧩 Multi-Image Combine and Edit API (FLUX.1 Kontext Max)

## Overview
Multi-Image List runs FLUX.1 Kontext [max] with a list of input images. Send several images in `input_images` and describe in `prompt` how to combine or transform them, for example placing a person or object from one image into the scene of another. Each request returns the URL of one generated image.

## Features
- **Several input images**: pass a list of image URLs (jpeg, png, gif or webp) in `input_images`.
- **Instruction prompt**: describe how to combine or transform the images in plain language. Refer to the images by their order in the list ("the first image", "the second image").
- **Aspect ratio**: `match_input_image` (default) matches the aspect ratio of the input image. 13 fixed ratios from `21:9` to `9:21` are also available.
- **Output format**: `png` (default) or `jpg`.
- **Safety tolerance**: 0 (most strict) to 2 (most permissive, the default and the maximum allowed).
- **Seed**: set a seed for reproducible results.

## Use Cases
1. **Scene compositing**: put a person, character or product from one photo into the setting of another.
2. **Product visuals**: place a product into a lifestyle or studio scene from a second image.
3. **Character and object mashups**: combine elements of several images into one new picture.
4. **Restyling with a reference**: transform one image using another image as the reference, described in the prompt.

## Visual Examples
### Example Input
Prompt: "Combine these photos into one scene: place the astronaut from the second image standing next to the woman in the yellow raincoat on the rainy neon-lit street from the first image, both looking up at the pink sign."

First image: a woman in a yellow raincoat on a rainy street at night under a pink neon sign.

![First input image: a woman in a yellow raincoat on a rainy street at night under a pink neon sign](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp)

Second image: a 3D astronaut figure on a grey background.

![Second input image: a 3D astronaut figure on a grey background](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp)

All other fields were left at their defaults (`aspect_ratio` `match_input_image`, `output_format` `png`).

### Example Output
![Multi-Image List output: the astronaut and the woman in the yellow raincoat combined into one rainy neon-lit street scene](https://blog.api.market/wp-content/uploads/2026/10/multi-image-list-output-api-market.jpg)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | Yes |  |  | Text description of how to combine or transform the input images |
| `input_images` | array of strings (URLs) | Yes |  |  | List of input images. Must be jpeg, png, gif or webp |
| `aspect_ratio` | string | No | `match_input_image` | `match_input_image`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `4:5`, `5:4`, `21:9`, `9:21`, `2:1`, `1:2` | Aspect ratio of the generated image. Use `match_input_image` to match the aspect ratio of the input image |
| `output_format` | string | No | `png` | `jpg`, `png` | Output format for the generated image |
| `safety_tolerance` | integer | No | `2` | 0 to 2 | Safety tolerance, 0 is most strict and 2 is most permissive. 2 is currently the maximum allowed |
| `seed` | integer | No | none |  | Random seed. Set for reproducible generation |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.10 per API unit.
- **1 API unit = 1 output image.** Each request returns one image, so each successful request costs $0.10, however many images you send in `input_images`.
- The example on this page (two input images, one output image) cost $0.10.
- **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 go to: `https://prod.api.market/api/v1/magicapi/multi-image-processing-api-flux-kontext-apps-multi-image-list`

### Authentication
Send your api.market API key in the `x-api-market-key` 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` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/multi-image-processing-api-flux-kontext-apps-multi-image-list/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "02f073c63abec2c72f0638164a25a64bd0ca70bce780c0ac75c6851252bb4c70",
    "input": {
      "prompt": "Combine these photos into one scene: place the astronaut from the second image standing next to the woman in the yellow raincoat on the rainy neon-lit street from the first image, both looking up at the pink sign.",
      "input_images": [
        "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp",
        "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
      ]
    }
  }'
```

Response (201 Created):
```json
{
  "id": "4cz2wfhzk5rmy0d17frafy6qac",
  "version": "02f073c63abec2c72f0638164a25a64bd0ca70bce780c0ac75c6851252bb4c70",
  "status": "starting",
  "created_at": "2026-10-14T19:42:43.219Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/multi-image-processing-api-flux-kontext-apps-multi-image-list/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "4cz2wfhzk5rmy0d17frafy6qac",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/multi-image-list-output-api-market.jpg",
  "error": null,
  "created_at": "2026-10-14T19:42:43.219Z",
  "started_at": "2026-10-14T19:42:44.219Z",
  "completed_at": "2026-10-14T19:42:58.219Z"
}
```

`output` is a single URL string pointing to the generated image.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a missing `prompt` or `input_images`, or an `aspect_ratio` that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

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

## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/multi-image-processing-api-flux-kontext-apps-multi-image-list";

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

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

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

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

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

  while (Date.now() - startTime < maxTimeout) {
    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(pollInterval);
  }

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

createAndWaitForPrediction({
  "prompt": "Combine these photos into one scene: place the astronaut from the second image standing next to the woman in the yellow raincoat on the rainy neon-lit street from the first image, both looking up at the pink sign.",
  "input_images": [
    "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp",
    "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
  ]
}).then((output) => console.log(output));
```

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

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/multi-image-processing-api-flux-kontext-apps-multi-image-list"

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": "02f073c63abec2c72f0638164a25a64bd0ca70bce780c0ac75c6851252bb4c70", "input": input_data},
    )

    if response.status_code != 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")

print(create_and_wait_for_prediction({
    "prompt": "Combine these photos into one scene: place the astronaut from the second image standing next to the woman in the yellow raincoat on the rainy neon-lit street from the first image, both looking up at the pink sign.",
    "input_images": [
        "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp",
        "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
    ]
}))
```

## FAQ
- **How do I tell the model which image is which?**
  - Refer to them by position in `input_images`, for example "the person from the first image" and "the background of the second image".
- **Do I pay more for more input images?**
  - No. You pay for the output image only: $0.10 per request.
- **What aspect ratio does the result have?**
  - By default `match_input_image`. Set `aspect_ratio` to a fixed value such as `16:9` or `1:1` to control the shape of the result.
- **How many images does one request return?**
  - One combined image per request, billed as one API unit ($0.10).
- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

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


Send several images and a prompt to FLUX.1 Kontext [max] and get one image that combines or transforms them. $0.10 per image, pay as you go.