GIFCOMPOSITE API Endpoint Documentation | PixLab Developers Handbook

API Endpoint Access URL

https://api.pixlab.io/gifcomposite

Get Your API Key & Try GIFCOMPOSITE Now ↗

Description

Composite one image onto a GIF at the specified offset. Use merge for other media format or if you want to merge more than two images into another. This endpoint is available starting from the Prod Plan and up.

HTTP Methods

GET, POST

HTTP Parameters

Required

Fields	Type	Description
`img`	URL	Input GIF URL. If you want to upload your GIF directly from your app, call store before invoking this one.
`composite`	URL	Composite image URL. If you want to upload the composite image directly from your app, call store before invoking this one.
`x`	Integer	The column offset of the composited image.
`y`	Integer	The row offset of the composited image.
`frame`	Integer	`Optional`: Start the merge process at this frame number.
`key`	String	Your PixLab API Key ↗. You can also embed your key in the `WWW-Authenticate:` HTTP header and omit this parameter if you want to.

Optional

Fields	Type	Description
`blob`	Boolean	By default, this API endpoint returns a JSON Object holding the link to the GIF output. If set to true, the GIF binary contents are returned instead.

POST Request Body

Use this if you plan to use POST instead of a simple GET request.

Allowed Content-Types:

multipart/form-data
application/json

Use multipart/form-data to upload media files directly (refer to the REST API code samples or The PixLab Github Repository↗ for a working example). For JSON, media files must be pre-uploaded. Call store to upload an image before invoking this endpoint.

HTTP Response

Fields	Type	Description
`status`	Integer	Status code 200 indicates success, any other code indicates failure.
`link`	URL	Link to the gif output which is usually stored on the pixlab.xyz storage server unless you set your own S3 keys (refer to your dashboard ↗ on how to do that).
`id`	String	Unique media ID.
`error`	String	Error message if `status` != 200.

The API returns application/json if the optional blob parameter is not set.

This endpoint returns a JSON Object after each call only if the optional blob parameter is omitted. Otherwise, the raw GIF binary data is returned directly. The JSON response contains the following fields:

Code Samples


import requests

def composite_gif(gif_url: str, static_image_url: str, x_pos: int, y_pos: int, start_frame: int, api_key: str) -> str:
    """Composite a static image on top of a GIF starting from specified frame.
    
    Args:
        gif_url: URL of the input GIF
        static_image_url: URL of the static image to composite
        x_pos: X position of the static image
        y_pos: Y position of the static image
        start_frame: Frame number to start compositing from
        api_key: PixLab API key
        
    Returns:
        URL of the processed GIF if successful, raises exception otherwise
    """
    params = {
        'img': gif_url,
        'composite': static_image_url,
        'x': x_pos,
        'y': y_pos,
        'frame': start_frame,
        'key': api_key
    }
    
    try:
        response = requests.get('https://api.pixlab.io/gifcomposite', params=params)
        response.raise_for_status()
        data = response.json()
        
        if data['status'] != 200:
            raise ValueError(f"API Error: {data.get('error', 'Unknown error')}")
            
        return data['link']
    
    except requests.exceptions.RequestException as e:
        raise ConnectionError(f"Request failed: {str(e)}")

# Example usage
if __name__ == "__main__":
    try:
        result_url = composite_gif(
            gif_url='http://i.stack.imgur.com/h8Hjm.gif',
            static_image_url='http://i.stack.imgur.com/WFr1K.png',
            x_pos=10,
            y_pos=30,
            start_frame=5,
            api_key='PIXLAB_API_KEY'
        )
        print(f"GIF location: {result_url}")
    except Exception as e:
        print(f"Error: {str(e)}")


const gif = 'http://i.stack.imgur.com/h8Hjm.gif';
const static = 'http://i.stack.imgur.com/WFr1K.png';
const params = new URLSearchParams({
    img: gif,
    composite: static,
    x: 10,
    y: 30,
    frame: 5,
    key: 'PIXLAB_API_KEY'
});

fetch(`https://api.pixlab.io/gifcomposite?${params}`)
    .then(response => response.json())
    .then(reply => {
        if (reply.status !== 200) {
            console.log(reply.error);
        } else {
            console.log(`GIF location: ${reply.link}`);
        }
    })
    .catch(error => console.error('Error:', error));

<?php

$gif = 'http://i.stack.imgur.com/h8Hjm.gif';
$static = 'http://i.stack.imgur.com/WFr1K.png';
$apiKey = 'PIXLAB_API_KEY';

$params = [
    'img' => $gif,
    'composite' => $static,
    'x' => 10,
    'y' => 30,
    'frame' => 5,
    'key' => $apiKey
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.pixlab.io/gifcomposite?' . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$reply = json_decode($response, true);

if ($reply['status'] != 200) {
    echo $reply['error'];
} else {
    echo "GIF location: " . $reply['link'];
}


require 'net/http'
require 'uri'
require 'json'

gif = 'http://i.stack.imgur.com/h8Hjm.gif'
static = 'http://i.stack.imgur.com/WFr1K.png'

uri = URI.parse('https://api.pixlab.io/gifcomposite')
params = {
  'img' => gif,
  'composite' => static,
  'x' => 10,
  'y' => 30,
  'frame' => 5,
  'key' => 'PIXLAB_API_KEY'
}
uri.query = URI.encode_www_form(params)

response = Net::HTTP.get_response(uri)
reply = JSON.parse(response.body)

if reply['status'] != 200
  puts reply['error']
else
  puts "GIF location: #{reply['link']}"
end

Similar API Endpoints

makegif, crop, resize, cropgif, merge, meme, facedetect, drawtext, scale, nsfw