API docs

Pick a template, set two colors, receive the finished emoji file. All requests go to https://tgemoji.app.

Quick start

1. Get an API key: open tgemoji.app/cabinet and log in with Telegram (the site gives you a code, and you confirm it in @TGemoji_app). Then press the button to create your key. The key is shown once, so save it.

2. Send your first request. This renders template 1 and saves it as a Telegram animated emoji file:

curl -X POST https://tgemoji.app/v1/render \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":1,"format":"tgs"}' \
  -o emoji_001.tgs

3. Upload the file to Telegram as a custom emoji. See Use in a Telegram bot.

Authentication

Send your API key in one of two headers. Keep the key private.

X-Api-Key: YOUR_API_KEY

# or

Authorization: Bearer YOUR_API_KEY

Requests without a valid key get 401. Limits per key are listed in Limits.

Templates

Browse the catalog, read one template, or fetch a preview. Browsing does not cost credits.

GET/v1/templates

Parameter	Description
page	Page number. Default 1
per_page	Templates per page. Default 50
category	Only templates from one category. Use a category slug, see below

Response (shortened)

{
  "total": 293,
  "page": 1,
  "per_page": 1,
  "items": [
    {
      "id": "001",
      "width": 512,
      "height": 512,
      "fps": 60,
      "frames": 157,
      "colors": {"main": "#FFFFFF", "secondary": "#B87003"},
      "category": "blue"
    }
  ]
}

The id is written with leading zeros. Use the number (1) as template_id when you render. colors shows the template's current main and second color. The response can contain more fields than shown here.

GET/v1/categories

Lists the categories you can pass as category. Current categories:

Slug	Name
blue	BLUE EMOJI
black	BLACK EMOJI
dark-blue	DARK BLUE EMOJI
frame	FRAME EMOJI
duck	DUCK EMOJI
symbols	SYMBOLS
blast-glow	BLAST GLOW

Response (shortened)

{
  "items": [
    {"slug": "blue", "name": "BLUE EMOJI", "count": 61},
    {"slug": "black", "name": "BLACK EMOJI", "count": 102}
  ]
}

count is the number of templates in the category.

GET/v1/templates/{id}

Returns one template with its editable colors.

GET/v1/templates/{id}/preview

Returns the animation as Lottie JSON, so you can show a preview on your site. Optional query parameters: color_main, color_secondary. Files for your customers always come from /v1/render.

The template id is its number, from 1 to 297. A few numbers are hidden, so the catalog lists 293 templates.

Render

Returns the finished emoji as a file. Each successful render costs 1 credit. Rendering the same request again costs another credit.

POST/v1/render

Field	Description
template_id	Required. Template number, 1 to 297
color_main	Optional. Replaces the template's main color
color_secondary	Optional. Replaces the second color
format	`json` (default) or `tgs`

Request body

{
  "template_id": 1,
  "color_main": "#F0C38E",
  "color_secondary": "#312C51",
  "format": "tgs"
}

Colors

A color is a 6-digit HEX value, with or without the #, in upper or lower case: #F0C38E, f0c38e. Short forms like #FFF and names like red are not accepted and return bad_color. If you leave a color out, the template keeps its original color.

Formats

Format	Use it for
tgs	Telegram. This is the animated sticker and custom emoji format (gzipped Lottie)
json	Websites and apps. Plain Lottie JSON that any Lottie player can show

Response

The response is the file itself (emoji_001.tgs or emoji_001.json). The header X-Credits-Left shows your remaining credits. If a request fails, no credit is taken.

Five templates have only one editable color. Gradients keep their original colors. The text inside templates cannot be changed.

Balance

Check your account name, credits, number of renders, your plan, and how many renders are left in the last 24 hours.

GET/v1/me

Response

{
  "name": "My Shop",
  "balance": 250,
  "renders": 12,
  "plan": "free",
  "daily_limit": 100,
  "daily_used": 12,
  "daily_left": 88
}

Errors

Errors come back as JSON with an error code and a message. Check the code in your program, not the message: message texts are written in Uzbek and may change.

Example

{
  "error": "insufficient_balance",
  "message": "Balans yetarli emas"
}

Status	Code	Meaning
400	bad_color	A color is not a 6-digit HEX value
400	bad_format	`format` is not `json` or `tgs`
401	invalid_key	The API key is wrong or disabled
402	insufficient_balance	No credits left. Nothing was rendered
404	template_not_found	The template does not exist
422	(no code)	The request body is invalid, for example `template_id` is missing. The body looks like `{"detail": [...]}`
429	rate_limited	More than 60 requests in a minute. Wait a moment
429	daily_limit	The daily render limit is used up

Limits

Limit	Value
Requests	60 per minute per key
Renders, free plan	100 per rolling 24 hours per key
Renders, pro plan	350 per rolling 24 hours per key. To switch to pro, message @TGemoji_app
Colors	2 per template (1 for five templates). Gradients stay as they are
Text	Text inside templates cannot be edited

Rendered files are for your own customers. Reselling or republishing the files as a collection is not allowed, see Terms.

Use in a Telegram bot

A .tgs file becomes a Telegram custom emoji once you add it to a custom emoji set. The Bot API does this with createNewStickerSet for the first emoji and addStickerToSet for the next ones.

Python: render, then create a set

import json
import requests

TGEMOJI_KEY = "YOUR_API_KEY"
BOT_TOKEN = "YOUR_BOT_TOKEN"
BOT_USERNAME = "your_bot"   # without @
USER_ID = 123456789         # Telegram user who owns the set
SET_NAME = "my_emoji_by_" + BOT_USERNAME

# 1) Render the emoji as TGS
r = requests.post(
    "https://tgemoji.app/v1/render",
    headers={"X-Api-Key": TGEMOJI_KEY},
    json={"template_id": 1, "color_main": "#F0C38E", "format": "tgs"},
)
r.raise_for_status()

# 2) Create a custom emoji set with that file
res = requests.post(
    f"https://api.telegram.org/bot{BOT_TOKEN}/createNewStickerSet",
    data={
        "user_id": USER_ID,
        "name": SET_NAME,
        "title": "My emoji",
        "sticker_type": "custom_emoji",
        "stickers": json.dumps([{
            "sticker": "attach://emoji",
            "format": "animated",
            "emoji_list": ["\U0001F600"],
        }]),
    },
    files={"emoji": ("emoji.tgs", r.content, "application/x-tgsticker")},
)
print(res.json())
# The set opens at https://t.me/addemoji/ + SET_NAME

The set name must end with _by_ and your bot's username.
Telegram has its own limits for TGS files (file size, length, canvas). If Telegram rejects a file, read its error text.
Telegram applies its own limits per bot, so create sets at a steady pace.

Code examples

Render template 1 as a TGS file and save it.

curl -X POST https://tgemoji.app/v1/render \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":1,"color_main":"#F0C38E","color_secondary":"#312C51","format":"tgs"}' \
  -o emoji_001.tgs

import requests

r = requests.post(
    "https://tgemoji.app/v1/render",
    headers={"X-Api-Key": "YOUR_API_KEY"},
    json={
        "template_id": 1,
        "color_main": "#F0C38E",
        "color_secondary": "#312C51",
        "format": "tgs",
    },
)
r.raise_for_status()
open("emoji_001.tgs", "wb").write(r.content)
print("Credits left:", r.headers["X-Credits-Left"])

const res = await fetch("https://tgemoji.app/v1/render", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template_id: 1,
    color_main: "#F0C38E",
    color_secondary: "#312C51",
    format: "tgs",
  }),
});
if (!res.ok) throw new Error(await res.text());
const file = await res.arrayBuffer();
console.log("Credits left:", res.headers.get("X-Credits-Left"));