Face Stickers API

Pixian.AI offers a unique face stickers API. The API creates fun and festive cutouts of faces, useful for both pets and people.

Get API Key

Quickstart

POST a bitmap image and get a face sticker result back:

$ curl https://api.pixian.ai/api/v2/face-sticker \
 -u xyz123:[secret] \
 -F image=@example.jpeg \
 -o pixian_result.png
// Requires: org.apache.httpcomponents.client5:httpclient5-fluent

Request request = Request.post("https://api.pixian.ai/api/v2/face-sticker")
   .addHeader("Authorization", "Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd")
   .body(
      MultipartEntityBuilder.create()
         .addBinaryBody("image", new File("example.jpeg")) // TODO: Replace with your image
         // TODO: Add more upload parameters here
         .build()
      );
ClassicHttpResponse response = (ClassicHttpResponse) request.execute().returnResponse();

if (response.getCode() == 200) {
   // Write result to disk, TODO: or wherever you'd like
   try (FileOutputStream out = new FileOutputStream("pixian_result.png")) {
      response.getEntity().writeTo(out);
   }
} else {
   System.out.println("Request Failed: Status: " + response.getCode() + ", Reason: " + response.getReasonPhrase());
}
using (var client = new HttpClient())
using (var form = new MultipartFormDataContent())
{
   client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", "INSERT_API_KEY_HERE");
   form.Add(new ByteArrayContent(File.ReadAllBytes("example.jpeg")), "image", "example.jpeg"); // TODO: Replace with your image
   // TODO: Add more upload parameters here

   var response = client.PostAsync("https://api.pixian.ai/api/v2/face-sticker", form).Result;

   if (response.IsSuccessStatusCode)
   {
      // Write result to disk, TODO: or wherever you'd like
      FileStream outStream = new FileStream("pixian_result.png", FileMode.Create, FileAccess.Write, FileShare.None);
      response.Content.CopyToAsync(outStream).ContinueWith((copyTask) => { outStream.Close(); });
   }
   else
   {
       Console.WriteLine("Request Failed: Status: " + response.StatusCode + ", Reason: " + response.ReasonPhrase);
   }
}
// Requires "request" to be installed (see https://www.npmjs.com/package/request)
var request = require('request');
var fs = require('fs');

request.post({
  url: 'https://api.pixian.ai/api/v2/face-sticker',
  formData: {
    image: fs.createReadStream('example.jpeg'), // TODO: Replace with your image
    // TODO: Add more upload options here
  },
  auth: {user: 'xyz123', pass: '[secret]'},
  followAllRedirects: true,
  encoding: null
}, function(error, response, body) {
  if (error) {
    console.error('Request failed:', error);
  } else if (!response || response.statusCode != 200) {
    console.error('Error:', response && response.statusCode, body.toString('utf8'));
  } else {
    // Save result
    fs.writeFileSync("pixian_result.png", body);
  }
});
$ch = curl_init('https://api.pixian.ai/api/v2/face-sticker');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER,
    array('Authorization: Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd'));
curl_setopt($ch, CURLOPT_POSTFIELDS,
    array(
      'image' => curl_file_create('example.jpeg'),
      // TODO: Add more upload options here
    ));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$data = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200) {
  // Save result
  file_put_contents("pixian_result.png", $data);
} else {
  echo "Error: " . $data;
}
curl_close($ch);
# Requires "requests" to be installed (see https://pypi.org/project/requests/)
import requests

response = requests.post(
    'https://api.pixian.ai/api/v2/face-sticker',
    files={'image': open('example.jpeg', 'rb')},
    data={
        # TODO: Add more upload options here
    },
    auth=('xyz123', '[secret]')
)
if response.status_code == requests.codes.ok:
    # Save result
    with open('pixian_result.png', 'wb') as out:
        out.write(response.content)
else:
    print("Error:", response.status_code, response.text)
# Requires: gem install httpclient
require 'httpclient'

client = HTTPClient.new default_header: {
  "Authorization" => "Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd"
}

response = client.post("https://api.pixian.ai/api/v2/face-sticker", {
  "image" => File.open("example.jpeg", "rb"), # TODO: Replace with your image
  # TODO: Add more upload parameters here
})

if response.status == 200 then
  # Write result to disk, TODO: or wherever you'd like
  File.open("pixian_result.png", 'w') { |file| file.write(response.body) }
else
  puts "Error: Code: " + response.status.to_s + ", Reason: " + response.reason
end
$ curl https://api.pixian.ai/api/v2/face-sticker \
 -u xyz123:[secret] \
 -F 'image.url=https://example.com/example.jpeg' \
 -o pixian_result.png
// Requires: org.apache.httpcomponents.client5:httpclient5-fluent

Request request = Request.post("https://api.pixian.ai/api/v2/face-sticker")
   .addHeader("Authorization", "Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd")
   .body(
      MultipartEntityBuilder.create()
         .addTextBody("image.url", "https://example.com/example.jpeg") // TODO: Replace with your image URL
         // TODO: Add more upload parameters here
         .build()
      );
ClassicHttpResponse response = (ClassicHttpResponse) request.execute().returnResponse();

if (response.getCode() == 200) {
   // Write result to disk, TODO: or wherever you'd like
   try (FileOutputStream out = new FileOutputStream("pixian_result.png")) {
      response.getEntity().writeTo(out);
   }
} else {
   System.out.println("Request Failed: Status: " + response.getCode() + ", Reason: " + response.getReasonPhrase());
}
using (var client = new HttpClient())
using (var form = new MultipartFormDataContent())
{
   client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", "INSERT_API_KEY_HERE");
   form.Add(new StringContent("https://example.com/example.jpeg"), "image.url"); // TODO: Replace with your image URL
   // TODO: Add more upload parameters here

   var response = client.PostAsync("https://api.pixian.ai/api/v2/face-sticker", form).Result;

   if (response.IsSuccessStatusCode)
   {
      // Write result to disk, TODO: or wherever you'd like
      FileStream outStream = new FileStream("pixian_result.png", FileMode.Create, FileAccess.Write, FileShare.None);
      response.Content.CopyToAsync(outStream).ContinueWith((copyTask) => { outStream.Close(); });
   }
   else
   {
       Console.WriteLine("Request Failed: Status: " + response.StatusCode + ", Reason: " + response.ReasonPhrase);
   }
}
// Requires "request" to be installed (see https://www.npmjs.com/package/request)
var request = require('request');
var fs = require('fs');

request.post({
  url: 'https://api.pixian.ai/api/v2/face-sticker',
  formData: {
    'image.url': 'https://example.com/example.jpeg', // TODO: Replace with your image
    // TODO: Add more upload options here
  },
  auth: {user: 'xyz123', pass: '[secret]'},
  followAllRedirects: true,
  encoding: null
}, function(error, response, body) {
  if (error) {
    console.error('Request failed:', error);
  } else if (!response || response.statusCode != 200) {
    console.error('Error:', response && response.statusCode, body.toString('utf8'));
  } else {
    // Save result
    fs.writeFileSync("pixian_result.png", body);
  }
});
$ch = curl_init('https://api.pixian.ai/api/v2/face-sticker');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER,
    array('Authorization: Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd'));
curl_setopt($ch, CURLOPT_POSTFIELDS,
    array(
      'image.url' => 'https://example.com/example.jpeg',
      // TODO: Add more upload options here
    ));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$data = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200) {
  // Save result
  file_put_contents("pixian_result.png", $data);
} else {
  echo "Error: " . $data;
}
curl_close($ch);
# Requires "requests" to be installed (see https://pypi.org/project/requests/)
import requests

response = requests.post(
    'https://api.pixian.ai/api/v2/face-sticker',
    data={
        'image.url': 'https://example.com/example.jpeg',
        # TODO: Add more upload options here
    },
    auth=('xyz123', '[secret]')
)
if response.status_code == requests.codes.ok:
    # Save result
    with open('pixian_result.png', 'wb') as out:
        out.write(response.content)
else:
    print("Error:", response.status_code, response.text)
# Requires: gem install httpclient
require 'httpclient'

client = HTTPClient.new default_header: {
  "Authorization" => "Basic cHh4YmJ6Yjk2bjJ3OGFtOltzZWNyZXRd"
}

response = client.post("https://api.pixian.ai/api/v2/face-sticker", {
  "image.url" => "https://example.com/example.jpeg", # TODO: Replace with your image URL
  # TODO: Add more upload parameters here
})

if response.status == 200 then
  # Write result to disk, TODO: or wherever you'd like
  File.open("pixian_result.png", 'w') { |file| file.write(response.body) }
else
  puts "Error: Code: " + response.status.to_s + ", Reason: " + response.reason
end

Pricing

It is free to integrate with and test out the API, no purchase required.

Just use test=true for development. You can assess the result quality using the interactive Web App on the front page.

Production results require a credit pack purchase. Please see the pricing page.

Authentication & Security

The API uses standard HTTP basic access authentication. All requests to the API must be made over HTTPS and include your API Credentials, with the API Id as the user and API Secret as the password.

Your http client library must support Server Name Indication (SNI) to successfully make requests. If you're getting weird handshake errors, this is most likely it.

Rate Limiting

Usage of the API is rate limited with generous allowances and no hard upper bound.

During normal end-user-driven operation you are unlikely to run into any rate limiting as usage then tends to ebb and flow in a way that the service handles gracefully.

However, for batch jobs we recommend starting out with at most 5 threads, adding 1 new thread every 5 minutes until you have reached the desired level of parallelism. Please reach out before starting if you need more than 100 concurrent threads.

If you submit too many requests you will start getting 429 Too Many Requests responses. When this happens you should apply linear back off: on the first such response, wait 5 seconds until submitting the next request. On the second consecutive 429 response, wait 2*5=10 seconds until submitting the next request. On the third wait 3*5=15 seconds, etc.

You can reset the back off counter after a successful request, and you should apply the back off on a per-thread basis (i.e. the threads should operate independently of each other).

Timeouts

While API requests are normally completed within seconds, it is possible during transient load spikes to experience longer processing times.

To ensure your client library doesn't prematurely terminate API requests it should be configured with an idle timeout of at least 180 seconds.

Error JSON Object

We use conventional HTTP statuses to indicate success or failure of an API request, and include important error information in the returned Error JSON Object.

We strive to always return an Error JSON Object with any problematic request. However, it is always theoretically possible to have internal server failures that lead to a non-JSON error response.

Attributes

statusThe HTTP status of the response, repeated here to help with debugging.
codePixian.AI internal error code.
messageHuman-readable error message, intended to be helpful in debugging.

If the HTTP status for your request is 200 then no Error JSON Object will be returned, and you can safely assume that the request broadly speaking succeeded.

Some HTTP Client libraries raise exceptions for HTTP statuses in the 400-599 range. You will need to catch those exceptions and handle them appropriately.

HTTP StatusMeaning
200-299

Success

400-499

There's a problem with the information provided in the request (e.g. a parameter was missing). Please review the error message to figure out how to fix it.

500-599

There's been a Pixian.AI internal error. Wait a moment then try again, and if the problem persists please email us.

Example Error Response

{
  "error" : {
    "status" : 400,
    "code" : 1006,
    "message" : "Failed to read the supplied image. "
  }
}

Face Stickers POST
https://api.pixian.ai/api/v2/face-sticker

To get a face sticker from an image, you do a standard HTTP POST file upload. Keep in mind that the Content-Type has to be multipart/form-data when uploading binary files.

Parameters

The input image must be provided as one of:


Binary

A binary file.


String

A base64-encoded string. The string can be at most 1 megabyte in size.


String

A URL to fetch and process.

Must be a .bmp, .gif, .jpeg, .png, or .tiff file.

The maximum image upload size (= width × height) is 32,000,000 pixels, which gets shrunk to max_pixels.


Boolean, default: false

Pass in true to indicate that this is a test image.

Omit or pass in false for production images.

Test images are free to process, but the result will have a watermark embedded.


Integer, 100 to 25000000, default: 25000000

The maximum input image size (= width × height). Images larger than this will be shrunk to this size before processing.


Format: '#RRGGBB', e.g. #0055FF

Background color to apply to the result. Omit to leave a transparent background.

Be sure to include the '#' prefix.


Boolean, default: true

Whether to crop the result to the foreground object.

Very useful together with result.margin and result.target_size to get a nicely sized and centered result every time.


Format: '(x.y%|px){1,4}', e.g. 10px 20% 5px 15%, default: 1px

Margin to add to the result.

It's added regardless of if the result is cropped to the foreground or not.

If result.target_size is specified, then the margin is inset, i.e. it doesn't expand the effective target size.

The supported units are % and px. It follows CSS semantics, so you can use any of:

  • [all]
  • [top/bottom] [left/right]
  • [top] [left/right] [bottom]
  • [top] [right] [bottom] [left]


Format: 'w h', e.g. 1920 1080

Enforce a specific result size in pixels. The result will be scaled to fit within the specified size. If there's excess space then it's always horizontally centered, with result.vertical_alignment controlling the vertical treatment.


Enum, default: middle

Specifies how to allocate excess vertical space when result.target_size is used.


Enum, default: auto

Output format. auto is interpreted as png for transparent results, and jpeg for opaque results, i.e. when a background.color has been specified.

delta_png is an advanced, fast, and highly compact format especially useful for low-latency, bandwidth-constrained situations like mobile apps. It encodes the background as transparent black 0x00000000 and the foreground as transparent white 0x00FFFFFF. Partially transparent pixels have their actual color values. Together with the input image you can use this to reconstruct the full result. Learn more about the Delta PNG format

background.color, result.crop_to_foreground, result.margin, result.target_size, and result.vertical_alignment are ignored when using delta_png. The result must be the same size as the input image, otherwise your decoding will fail, so max_pixels must not have caused the input to be shrunk.


Integer, 1 to 100, default: 75

The quality to use when encoding JPEG results.

Result Headers

X-Credits-Charged The actual credits charged.
X-Credits-Calculated The calculated credits that would have been charged if this were a production request. Only returned for test requests.
X-Input-Orientation The EXIF orientation tag we read from and applied to the input image. It's an integer value from 1 to 8, inclusive. This is useful if your image loading library doesn't support EXIF orientation. Read more about EXIF orientation here
X-Input-Size [width] [height] of the input image in pixels, before any size constraints were applied.
X-Result-Size [width] [height] of the result image, in pixels.
X-Input-Foreground [top] [left] [width] [height] bounding box of the foreground in the input image coordinates.
X-Result-Foreground [top] [left] [width] [height] bounding box of the foreground in the result image coordinates.

Face Stickers API Changelog

DateChange
Apr 11, 2024 Initial release.
Get API Key