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.


rendererStringN/A due to SVG file format
sizeIntegerN/A due to SVG file format
filenameStringkey-value pairs

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


  • 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:


      File returned: base-263a.png

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

      Example Request:


      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)

when output=jsonXML
when output=imageimage/svg+xml

PNG (file_format=png)

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


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.


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.


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:

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