Effortlessly Merge Images with the lucataco/merge-img Cognitive Actions

21 Apr 2025
Effortlessly Merge Images with the lucataco/merge-img Cognitive Actions

In the realm of image processing, the ability to seamlessly combine images is crucial for various applications, from web design to digital art. The lucataco/merge-img API offers a powerful Cognitive Action that enables developers to merge a foreground image with a background image effortlessly. This article will guide you through the capabilities of this action, detailing how you can integrate it into your applications to create stunning composite images.

Prerequisites

Before you start using the Cognitive Actions, ensure you have:

  • An API key for accessing the Cognitive Actions platform.
  • Familiarity with making HTTP requests and handling JSON data.

Authentication typically involves passing your API key in the request headers as a Bearer token. This ensures secure access to the service.

Cognitive Actions Overview

Merge Foreground and Background Images

This action allows you to combine a foreground PNG image with a background JPG image, with the flexibility to specify the positioning of the foreground image.

Input

The input for this action requires the following fields:

  • foreground (string): The URI to a PNG image with transparency intended for the foreground layer.
  • background (string): The URI to a JPG image that will serve as the background layer.
  • positionX (integer, optional): The X coordinate for the position of the foreground image. If not specified, it defaults to the center of the background image.
  • positionY (integer, optional): The Y coordinate for the position of the foreground image. If not specified, it defaults to the center of the background image.

Example Input:

{
  "background": "https://replicate.delivery/pbxt/MGREFtOoq1mHLtFubZD9jrM0PfGuaGbrI9Z9lbHns7YFdsdi/replicate-prediction-8hepgs9evnrga0cm69rbpaehv8.jpg",
  "foreground": "https://replicate.delivery/pbxt/MGREFYPiuQLuj97mLLuBHlKkNHwg8yggdk4fgQT3zxrU6ABM/cologne.png"
}

Output

The action will return a URI to the newly created composite image. The output generally looks like this:

Example Output:

https://assets.cognitiveactions.com/invocations/8d8bd220-9d9e-40a6-b443-e1405acc3b68/7a08fb8e-3d01-4bc2-9c34-0e8731c2aff3.jpg

Conceptual Usage Example (Python)

Here’s how you might call this action using a conceptual Python code snippet. This will help you structure your input JSON payload and make a request to the Cognitive Actions endpoint.

import requests
import json

# Replace with your Cognitive Actions API key and endpoint
COGNITIVE_ACTIONS_API_KEY = "YOUR_COGNITIVE_ACTIONS_API_KEY"
COGNITIVE_ACTIONS_EXECUTE_URL = "https://api.cognitiveactions.com/actions/execute"  # Hypothetical endpoint

action_id = "cfe910c0-874f-45a4-ad0d-a74e8813fadf"  # Action ID for Merge Foreground and Background Images

# Construct the input payload based on the action's requirements
payload = {
    "background": "https://replicate.delivery/pbxt/MGREFtOoq1mHLtFubZD9jrM0PfGuaGbrI9Z9lbHns7YFdsdi/replicate-prediction-8hepgs9evnrga0cm69rbpaehv8.jpg",
    "foreground": "https://replicate.delivery/pbxt/MGREFYPiuQLuj97mLLuBHlKkNHwg8yggdk4fgQT3zxrU6ABM/cologne.png"
}

headers = {
    "Authorization": f"Bearer {COGNITIVE_ACTIONS_API_KEY}",
    "Content-Type": "application/json"
}

try:
    response = requests.post(
        COGNITIVE_ACTIONS_EXECUTE_URL,
        headers=headers,
        json={"action_id": action_id, "inputs": payload}  # Hypothetical structure
    )
    response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)

    result = response.json()
    print("Action executed successfully:")
    print(json.dumps(result, indent=2))

except requests.exceptions.RequestException as e:
    print(f"Error executing action {action_id}: {e}")
    if e.response is not None:
        print(f"Response status: {e.response.status_code}")
        try:
            print(f"Response body: {e.response.json()}")
        except json.JSONDecodeError:
            print(f"Response body: {e.response.text}")

In this snippet:

  • Replace YOUR_COGNITIVE_ACTIONS_API_KEY with your actual API key.
  • The action_id is set to the ID of the Merge Foreground and Background Images action.
  • The payload variable contains the required input for the action.

Conclusion

The Merge Foreground and Background Images action within the lucataco/merge-img API provides a straightforward way to create composite images by layering a foreground image over a background. With just a few lines of code, you can enrich your applications with dynamic image processing capabilities. Consider exploring various use cases, such as creating personalized graphics, enhancing user interfaces, or automating content generation. Happy coding!

← Back to All Articles