Overlay Images

Place one image on top of another with control over position, opacity, and blending mode.

Request Parameters

Response

Returns the combined image with the overlay applied, in the same format as the base image.

Example Request

    // example.sh
curl -X POST "https://oyyi.xyz/api/image/overlay"   -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "base_file=@background.jpg" \
  -F "overlay_file=@logo.png" \
  -F "x_offset=0" \
  -F "y_offset=0" \
  -F "opacity=1.0" \
  --output overlaid.jpg
  

Example with Python

    // overlay.py
import requests

url = "https://oyyi.xyz/api/image/overlay"

files = {
    'base_file': open('background.jpg', 'rb'),
    'overlay_file': open('logo.png', 'rb')
}

data = {
    'x_offset': 50,
    'y_offset': 50,
    'opacity': 0.8
}

response = requests.post(url, files=files, data=data)

# Save the overlaid image
with open('overlaid.jpg', 'wb') as f:
    f.write(response.content)
  

Example with JavaScript

    // overlay.js
// Using fetch API
const formData = new FormData();
formData.append('base_file', baseImageInput.files[0]);
formData.append('overlay_file', overlayImageInput.files[0]);
formData.append('x_offset', '50');
formData.append('y_offset', '50');
formData.append('opacity', '0.8');

fetch('https://oyyi.xyz/api/image/overlay', {
  method: 'POST',
  body: formData
})
.then(response => response.blob())
.then(blob => {
  // Create a URL for the blob
  const url = URL.createObjectURL(blob);

  // Create a link to download the image
  const a = document.createElement('a');
  a.href = url;
  a.download = 'overlaid.jpg';
  a.click();

  // Clean up by revoking the URL
  URL.revokeObjectURL(url);
})
.catch(error => console.error('Error:', error));
  

Predefined Positions

Blend Modes

How It Works

The overlay endpoint combines two images by placing one on top of the other:

1. Image Loading: Both the base and overlay images are loaded.
2. Overlay Preparation: The overlay image is scaled (if specified) and rotated (if specified).
3. Position Calculation: The position of the overlay is determined based on the specified offsets or predefined position.
4. Opacity Adjustment: The overlay's opacity is adjusted according to the opacity parameter.
5. Blending: The overlay is combined with the base image using the specified blend mode.
6. Compositing: The final image is created by compositing the overlay onto the base image.

The result is a combined image that can be used for adding logos, watermarks, or creating composite images.

Error Responses

Notes

• For transparent overlays, use PNG or WebP formats with alpha channels.
• The position parameter provides a convenient way to place the overlay at common locations without calculating exact pixel offsets.
• Negative offset values are allowed and can be used to position the overlay partially outside the base image (the overflow will be cropped).
• The scale parameter is useful for resizing the overlay without having to create a separate resized version.
• Blend modes can create interesting visual effects when combining images.
• The maximum file size allowed for each image is 10MB.
• The output format will match the format of the base image.

Use Cases

• Adding logos or branding to images
• Creating composite images for marketing or social media
• Adding decorative elements or frames to photos
• Placing product images on different backgrounds
• Creating collages or montages
• Adding badges or icons to profile pictures
• Creating before/after comparisons with partial overlays