Name: FLUX Kontext Pro – AI Image Combiner | $0.05/call | API.market
Brand: magicapi
SKU: api-magicapi-ai-image-combiner-api
Availability: InStock
Rating: 5.00 (1 reviews)
Author: API Market

Shashank Agarwal

# 🖼️ AI Image Combiner API (FLUX Kontext Pro) - Seamless Merging

## Overview
The AI Image Combiner API (FLUX Kontext Pro) makes it easy to merge two images into a single, unified composition. Powered by advanced AI image processing, this API can help you blend visual elements quickly, making it ideal for creative designs, marketing materials, and media production. You simply provide two images, along with a brief textual prompt on how you want them combined, and the API will return a new, expertly fused image.

![Example output showing two images blended together](https://replicate.delivery/xezq/U6C6Sv9a185eU6VesDUyc167QOfHFOjhijVJ28W2eKR276MTB/tmp7exxygto.png)

## Features
- Seamless merging of two images into one
- High-quality image processing with fast AI-driven results
- Flexible aspect ratios and output formats
- Configurable safety tolerance to filter out unwanted content
- Asynchronous processing for reliable background execution

## Use Cases

1. **Marketing Collateral Creation**  
   Perfect for quickly combining product photos and background imagery to create attractive advertisements, landing page banners, or promotional graphics.

2. **Social Media Content**  
   Generate eye-catching collages or side-by-side comparisons of items for social media posts—ideal for influencers, eCommerce brands, or event promotions.

3. **News & Media**  
   Combine relevant images for editorial content, such as placing a subject’s image next to a notable scene or location for feature articles and blogs.

4. **Creative Storytelling**  
   Merge characters or objects into backdrop scenes for comics, storyboards, or digital art without advanced graphic design tools.

5. **E-Learning Resources**  
   Enhance training materials by merging example diagrams or images into a single, comprehensive visual aid.

## Visual Examples

Below are example inputs and output provided by the API. The prompt in these examples instructs the API to combine the images:

### Input Image 1
![Input image 1](https://replicate.delivery/pbxt/N7gRAUNcVF6HarL0hdAQA2JYNMlJD52LP1wyaIWRUXWeHzqT/0_1-1.webp)  
(This image could represent one of the subjects or background elements.)

### Input Image 2
![Input image 2](https://replicate.delivery/pbxt/N7gRAK5kbPwdsbOpqgyAIOFQX45U6suTlbL6ws2N74SnGFpo/test.jpg)  
(This image could represent another subject or scene to combine with the first.)

### Example Prompt
“Put the woman next to the house.”

### Resulting Output
![Combined output image](https://replicate.delivery/xezq/U6C6Sv9a185eU6VesDUyc167QOfHFOjhijVJ28W2eKR276MTB/tmp7exxygto.png)  
(The resulting image shows how the two inputs are blended together.)

## Pricing
- 1 API unit = 1 image processed (in this case, each merge request counts as processing two images together into one).
- GET requests that check prediction status (GET /api/v1/magicapi/ai-image-combiner-api/predictions/{id}) are free and do not count toward API unit usage.
- Pricing tiers vary based on usage volume. Higher volume tiers offer lower per-unit costs.

## API Documentation

### Base URL
All requests to this API should be sent to:  
```
https://prod.api.market/api/v1/magicapi/ai-image-combiner-api
```

### Authentication
Include your API key in the request header:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
This API processes image merges asynchronously. The process typically follows these steps:

1. Send a POST request to create a new prediction (image merge).  
2. Receive a response containing a unique prediction ID.  
3. Use that ID in repeated GET requests to check the status.  
4. When the status is "succeeded," you can retrieve the merged image from the output URL.

We recommend polling once per second and timing out after 10 minutes (600 seconds). Stop polling when:
- The status is "succeeded" (result is ready).  
- The status is "failed" (an error occurred).  
- The timeout is reached.

### Endpoints

#### 1. Create a Prediction

• **Endpoint**:  
  POST /api/v1/magicapi/ai-image-combiner-api/predictions  

• **Description**:  
  Initiates the merging (prediction) process by providing the model with the two images and a brief prompt.

• **Request Body** (JSON):
```json
{
  "version": "6d14f9b3d25a9400c4a5e5f0f6842ae7537fefcf68df86dad9533f66204f2bb2",
  "input": {
    "prompt": "Put the woman next to the house",
    "aspect_ratio": "match_input_image",
    "input_image_1": "https://replicate.delivery/pbxt/N7gRAUNcVF6HarL0hdAQA2JYNMlJD52LP1wyaIWRUXWeHzqT/0_1-1.webp",
    "input_image_2": "https://replicate.delivery/pbxt/N7gRAK5kbPwdsbOpqgyAIOFQX45U6suTlbL6ws2N74SnGFpo/test.jpg",
    "output_format": "png",
    "safety_tolerance": 2
  }
}
```

• **Response** (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "6d14f9b3d25a9400c4a5e5f0f6842ae7537fefcf68df86dad9533f66204f2bb2",
  "status": "starting",
  "created_at": "2025-06-05T20:02:29.981Z"
}
```

**Example cURL**:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-image-combiner-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "6d14f9b3d25a9400c4a5e5f0f6842ae7537fefcf68df86dad9533f66204f2bb2",
    "input": {
      "prompt": "Put the woman next to the house",
      "aspect_ratio": "match_input_image",
      "input_image_1": "https://replicate.delivery/pbxt/N7gRAUNcVF6HarL0hdAQA2JYNMlJD52LP1wyaIWRUXWeHzqT/0_1-1.webp",
      "input_image_2": "https://replicate.delivery/pbxt/N7gRAK5kbPwdsbOpqgyAIOFQX45U6suTlbL6ws2N74SnGFpo/test.jpg",
      "output_format": "png",
      "safety_tolerance": 2
    }
  }'
```

#### 2. Get Prediction Status and Results

• **Endpoint**:  
  GET /api/v1/magicapi/ai-image-combiner-api/predictions/{id}

• **Description**:  
  Retrieve the current status of a prediction (image merge). If the merge is complete, the response includes an output URL to the merged image.

• **Path Parameters**:
- **id** (required): The unique prediction ID returned from the POST request.

• **Response** (200 OK on success):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://replicate.delivery/xezq/U6C6Sv9a185eU6VesDUyc167QOfHFOjhijVJ28W2eKR276MTB/tmp7exxygto.png",
  "error": null,
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

**Example cURL**:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-image-combiner-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Status Codes
- **200 OK**: Request successful  
- **201 Created**: Resource successfully created (e.g., new prediction)  
- **400 Bad Request**: Invalid parameters or malformed request  
- **401 Unauthorized**: Missing or invalid API key  
- **403 Forbidden**: The API key is valid but does not have sufficient permissions  
- **404 Not Found**: The requested resource (prediction ID) does not exist  
- **429 Too Many Requests**: You have exceeded the rate limit or quota  
- **500 Internal Server Error**: A server-side error occurred  
- **503 Service Unavailable**: The service is temporarily offline or overloaded

### Rate Limits
This API may impose limits to ensure quality of service. If you exceed these limits, you may receive a 429 (Too Many Requests) response. To handle this scenario, implement a backoff strategy (wait for a short period before retrying), or consider upgrading to a higher-volume plan.

### Error Handling
When an error occurs, the API returns a JSON response with details:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'prompt' is invalid or missing",
    "status": 400
  }
}
```

Key recommendations for error handling:
1. Check the HTTP status code before processing the response body.  
2. For 400-series errors, correct the request based on the error message.  
3. For 500-series errors, implement a retry strategy in case of transient failures.  
4. For 429 (Too Many Requests), implement a backoff strategy or reduce request frequency.

## Implementation Guide

Below are sample code snippets demonstrating how to create a prediction and then poll the API until the merge is complete.

### JavaScript Example (Node.js)

```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/ai-image-combiner-api";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "6d14f9b3d25a9400c4a5e5f0f6842ae7537fefcf68df86dad9533f66204f2bb2",
        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
  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    await delay(POLL_INTERVAL);
  }

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

### Python Example

```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/ai-image-combiner-api"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={
            "version": "6d14f9b3d25a9400c4a5e5f0f6842ae7537fefcf68df86dad9533f66204f2bb2",
            "input": input_data
        }
    )

    if response.status_code != 200 and response.status_code != 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
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        headers = {"x-magicapi-key": API_KEY}
        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"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")

        time.sleep(POLL_INTERVAL)

    raise Exception("Prediction timed out after 10 minutes")
```

### cURL Example

```bash
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/ai-image-combiner-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "6d14f9b3d25a9400c4a5e5f0f6842ae7537fefcf68df86dad9533f66204f2bb2",
    "input": {
      "prompt": "Put the woman next to the house",
      "aspect_ratio": "match_input_image",
      "input_image_1": "https://replicate.delivery/pbxt/N7gRAUNcVF6HarL0hdAQA2JYNMlJD52LP1wyaIWRUXWeHzqT/0_1-1.webp",
      "input_image_2": "https://replicate.delivery/pbxt/N7gRAK5kbPwdsbOpqgyAIOFQX45U6suTlbL6ws2N74SnGFpo/test.jpg",
      "output_format": "png",
      "safety_tolerance": 2
    }
  }'

# Example response:
# {
#   "id": "abcd1234",
#   "status": "starting"
# }

# Step 2: Poll for the prediction status (replace abcd1234 with the actual ID)
curl -X GET "https://prod.api.market/api/v1/magicapi/ai-image-combiner-api/predictions/abcd1234" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

### Performance Optimization
- Combine requests or batch operations when possible.
- Use the smallest image size that meets your quality requirements to reduce processing time.
- Cache results if reusing the same inputs and prompt combinations to avoid repeated processing.
- Monitor your usage and upgrade to a higher-tier plan if you need higher throughput.

## FAQ
1. **How long does merging two images typically take?**  
   It generally completes within a few seconds, although more complex merges or high server load can cause slight delays.  

2. **Do I get charged for checking the status repeatedly?**  
   No. GET requests for checking predictions do not count against your usage credits.  

3. **What image formats are supported for input?**  
   JPEG, PNG, GIF, or WEBP are supported as input_image_1 and input_image_2.  

4. **Can I specify an exact width and height for the output?**  
   Currently, you can specify an aspect ratio. If you need further customization, you can post-process the returned image or adjust the prompt.  

5. **What if I need higher resolution outputs?**  
   Adjust your request or consider contacting support about advanced custom integrations.

## 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[at]api.market.

Combine two images into a single composition with a text prompt. Fast, AI-powered processing for creative and media applications Try it free on API.market.

FLUX Kontext Pro – AI Image Combiner | $0.05/call | API.market

🖼️ AI Image Combiner API (FLUX Kontext Pro) - Seamless Merging

PAYG

MagicAPI

Effortlessly combine two images into a single, unified composition with high quality and fast AI-powered processing—perfect for creative and media applications