Видео и карточки подарков Telegram по одному запросу

Тарифы

Тариф — это объём запросов на месяц. Форматы можно смешивать: каждый запрос берёт свою долю тарифа.

Сколько запросов одного формата даёт тариф

Замедленное видео ½× считается как 2 видео, ⅓× и ¼× — как 3. Неудачный запрос не списывается. Остаток тарифа переносится при продлении.

Нужно больше, чем «Бизнес», — Enterprise: свой объём, дневной лимит и приоритет. Калькулятор — в кабинете API. Оплата — GRAM: переводом с комментарием (мемо) или счётом в xRocket.

Быстрый старт

1. Открой кабинет API (в боте — /api) и нажми «Создать API-ключ»: название, сервис и пара слов о проекте. Ключ показывается один раз — сохрани его. В кабинете — остаток, статистика и пополнение.
2. Передавай ключ в каждом запросе: Authorization: Bearer nfp_… (или заголовок X-API-Key).
3. Отправь задачу в POST /v1/render с "wait": 60 — ответ придёт, когда файл готов, со ссылкой file_url.
4. Скачай файл по file_url с тем же ключом. Файл хранится 1 час.

curl -X POST https://bot-production-b17c.up.railway.app/v1/render \
  -H "Authorization: Bearer $NFP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"gift": "https://t.me/nft/PlushPepe-22", "format": "mp4", "wait": 60}'

Ключ и лимиты

Каждый запрос — с ключом в заголовке Authorization: Bearer <ключ> или X-API-Key: <ключ>. Ключ создаётся в кабинете API, у одного человека — до 3 ключей, у каждого свой тариф, остаток и статистика. Ключ можно перевыпустить в кабинете: старый сразу перестаёт работать.

Как указать подарок

Одним из двух способов — в любом формате, кроме коллажа (у него список, см. ниже).

Настоящий подарок

Поле gift: ссылка https://t.me/nft/PlushPepe-22, t.me/nft/PlushPepe-22 или просто слаг PlushPepe-22. Модель, фон и символ берутся настоящие, номер — из ссылки.

Любое сочетание (как в Конструкторе)

Поля collection + model + backdrop, по желанию symbol и number. Названия — как в Telegram (Plush Pepe, Aqua Plush, Electric Purple, Star). Можно собрать и несуществующую комбинацию. Без symbol — фон без узора, number (до 7 цифр) рисуется на карточке и ленте коллажа.

{ "gift": "PlushPepe-22", "format": "png" }

{ "collection": "Plush Pepe", "model": "Aqua Plush", "backdrop": "Electric Purple",
  "symbol": "Star", "number": "777", "format": "card" }

Форматы

Формат выбирается полем format. Цена в единицах тарифа — в скобках (1 = один PNG).

{
  "collection": "Plush Pepe", "model": "Aqua Plush", "backdrop": "Electric Purple", "symbol": "Star",
  "colors": { "center": "#c27ce6", "edge": "#8a4fc0", "pattern": "#6b2fa3", "text": "#f1d2ff" },
  "build": {
    "backdrop": { "name": "Electric Purple", "rarity": "2%", "center": "#c27ce6", "edge": "#8a4fc0", "pattern": "#6b2fa3", "text": "#f1d2ff" },
    "symbol":   { "name": "Star", "rarity": "0.4%", "color": "#6b2fa3",
                  "lottie": "https://bot-production-b17c.up.railway.app/cdn/patterns/Plush%20Pepe/lottie/Star.json", "png": "https://bot-production-b17c.up.railway.app/cdn/patterns/Plush%20Pepe/png/Star.png" },
    "model":    { "name": "Aqua Plush", "rarity": "1.2%",
                  "lottie": "https://bot-production-b17c.up.railway.app/cdn/models/Plush%20Pepe/lottie/Aqua%20Plush.json", "png": "https://bot-production-b17c.up.railway.app/cdn/models/Plush%20Pepe/png/Aqua%20Plush.png" }
  },
  "rarity": { "model": "1.2%", "backdrop": "2%", "symbol": "0.4%" },
  "animation": { "fps": 60, "frames": 180, "duration_sec": 3.0 },
  "slug": "PlushPepe-22", "number": 22, "link": "https://t.me/nft/PlushPepe-22"
}

Рендер

Ставит задачу в очередь. Тело — JSON со всеми полями ниже (подарок + формат + параметры формата).

Ответ — 202, пока задача в работе, и 200, когда она закончилась:

{
  "ok": true,
  "job_id": "3f1c9a…",
  "status": "done",
  "format": "mp4",
  "file_url": "https://…/v1/jobs/3f1c9a…/file",
  "content_type": "video/mp4",
  "file_name": "PlushPepe-22.mp4",
  "size": 1843221,
  "render_ms": 4120,
  "expires_at": 1763140800,
  "cost": 10,
  "credits_left": 1990
}

Задачи и файлы

Статус задачи — те же поля, что у ответа рендера. Принимает ?wait= (до 90 с): удобно ждать готовности одним запросом вместо частых опросов.

Сам файл, с тем же ключом. Задача видна только ключу, которым её поставили. Через час после готовности файл и задача удаляются.

Ключ и остаток

Тариф, остаток и лимиты ключа. Остаток credits — в единицах тарифа: PNG — 1, JSON — 1, Lottie и TGS — 2, SVG — 3, видео и GIF — 10, карточка — 2 (PNG) или 10 (видео, GIF), коллаж PNG — 1 за каждые 3 подарка, коллаж-видео — 3 за подарок.

{
  "ok": true,
  "key": { "name": "Gift Market Bot", "hint": "9f3a" },
  "plan": "start",
  "plan_until": 1765900000,
  "credits": { "plan": 23410, "pack": 10000, "total": 33410 },
  "limits": { "rps": 2, "parallel_jobs": 2, "daily_credits": 3000 },
  "today": { "renders": 59, "credits": 590 },
  "renders_total": 412,
  "credits_spent": 8120,
  "costs": { "png": 1, "mp4": 10, "gif": 10, "card": 10, "card_png": 2, … }
}

Ошибки

Ошибка всегда приходит JSON-ом: {"ok": false, "error": "код", "message": "текст"}. В message — объяснение по-русски.

Советы

• Используй wait — один запрос вместо опросов. Если пришёл queued, жди через GET /v1/jobs/{id}?wait=60.
• На 429 и 503 повторяй с паузой, растущей с каждой попыткой (1, 2, 4… секунды).
• Кэшируй у себя: одинаковый запрос даёт одинаковый файл, а файл у нас живёт только час.
• Для витрин маркета дешевле всего png и json; для анимаций на сайте — lottie (лёгкий и чёткий на любом экране).
• Ключ — секрет: вызывай API со своего сервера, не из браузера пользователя.

Примеры

import requests

API = "https://bot-production-b17c.up.railway.app"
H = {"Authorization": "Bearer nfp_…"}

# карточка собранного подарка, замедленная в 2 раза
r = requests.post(f"{API}/v1/render", headers=H, json={
    "collection": "Plush Pepe", "model": "Aqua Plush",
    "backdrop": "Electric Purple", "symbol": "Star",
    "format": "card", "card_format": "mp4", "speed": 0.5, "wait": 90,
}).json()

while r["status"] in ("queued", "rendering"):
    r = requests.get(f"{API}/v1/jobs/{r['job_id']}?wait=60", headers=H).json()

if r["status"] == "done":
    open(r["file_name"], "wb").write(requests.get(r["file_url"], headers=H).content)
else:
    print("ошибка:", r.get("error"))

const API = "https://bot-production-b17c.up.railway.app";
const H = { Authorization: "Bearer nfp_…", "Content-Type": "application/json" };

let r = await fetch(`${API}/v1/render`, {
  method: "POST", headers: H,
  body: JSON.stringify({ gift: "PlushPepe-22", format: "gif", wait: 60 }),
}).then(x => x.json());

while (r.status === "queued" || r.status === "rendering") {
  r = await fetch(`${API}/v1/jobs/${r.job_id}?wait=60`, { headers: H }).then(x => x.json());
}
if (r.status === "done") {
  const gif = await fetch(r.file_url, { headers: H }).then(x => x.arrayBuffer());
}

# 1) поставить задачу и дождаться
curl -s -X POST https://bot-production-b17c.up.railway.app/v1/render \
  -H "Authorization: Bearer $NFP_KEY" -H "Content-Type: application/json" \
  -d '{"gift":"PlushPepe-22","format":"png","wait":60}'

# 2) скачать файл по file_url из ответа
curl -s -H "Authorization: Bearer $NFP_KEY" -o gift.png "FILE_URL"