Custom Faces Endpoints

Custom faces are Twemojis supported as faces that are combined to create new, unique emojis.

Learn more about supported faces via the /faces endpoints.

Arguments

NameRequiredTypeDefault
order❌Stringhead,cheeks,mouth,nose,eyes,eyewear,headwear,other
output❌StringJSON
file_format❌StringSVG
renderer❌StringN/A due to SVG file format
size❌IntegerN/A due to SVG file format
padding❌Integer0
background_color❌Stringtransparent
filename❌Stringkey-value pairs
twemoji_version❌Stringlatest

Emoji Formats

A number of different formats are supported for passing in emojis to promote ease of use.

  • glyph: 🙂
  • case insensitive codepoint: 1f642 or U+1f642
  • number representation: 128578

Stacking Order

Default order from bottom to top:

  1. head
  2. cheeks
  3. mouth
  4. nose
  5. eyes
  6. eyewear
  7. headwear
  8. other

To specify a custom stacking order, pass in the key-value pair order=manual anywhere in the request. The stacking will follow the order the parameters are passed in, with the first parameter being at the bottom.

left to right = bottom to top

Output

  • JSON (output=json)
    • Main response listed under data
    • Licensing information and links are also included
  • image (output=image)
  • download (output=download)

    • The default name of the file returned is the emoji described in key-value pairs

    • The equals signs (=) and ampersands (&) are replaced with a minus sign (-) and these characters _-_

      Example Request:

      1/v1/custom_faces/263a?file_format=png&output=download

      File returned: base-263a.png

    • To specify a custom filename on download, use the filename argument

      Example Request:

      1/v1/custom_faces/263a?file_format=png&output=download&filename=amazing_emoji

      File returned: amazing_emoji.png

File Format

File format refers to the type of image that is generated. Changing this argument changes other argument defaults.

SVG (file_format=svg)

ArgumentDefault
when output=jsonXML
when output=imageimage/svg+xml
size100%
paddingN/A

PNG (file_format=png)

ArgumentDefault
when output=jsonBase64
when output=imageMIME type of image/png
size128 (ideal for Slack)
padding0
renderer when output=json or output=downloadimagemagick
renderer when output=imagecanvg

Renderer

When querying for a PNG, a renderer is used. The default is imagemagick, but canvg is also available for browser usage returning content-type text/html.

Size

Specify the size of the output in pixels with an integer (e.g. size=500). It will always be a square so height and width are equal.

Padding

Add padding between the emoji and the edge of the output. Specify the number of pixels of the padding with an integer (e.g. padding=100).

This reduces the size of the emoji, but not the size of the output. So in the case of size=500&padding=100 the output will be 500px and the emoji 300px, since the padding is applied on all sides.

Background Color

Specify a background color with a string (e.g. background_color=red). Formats supported:

TypeExample
HTML color namesyellow
escaped hexadecimal values#bbbbbb escaped is %23bbbbbb
escaped RGB/RGBA valuesrgb(100% 0% 0%) escaped is rgb%28100%25%200%25%200%25%29
escaped HSL/HSLA valueshsl(120 50% 50%) escaped is hsl%28120%2050%25%2050%25%29