Telegram and Discord bot

The SpicyAPI bot is a small program you run yourself. It connects to Telegram (and, if you want, Discord) and lets the people you allow generate images, make videos, turn images into videos and chat with characters you define. Everything is paid from your own SpicyAPI balance, and every request is priced before anything is charged.

The bot is free and open source (MIT) at github.com/spicyapi-ai/spicyapi-bot. It is private by default: only you can use it until you allow other people or groups.

What the bot does

• Images: /pic a lighthouse at dusk
• Videos: /vid waves rolling onto a beach at sunset
• Animate: tap Animate under any image the bot made, or reply to it with /animate <how it should move>.
• Character chat: type in a private chat, or use /talk. Replies stream into one message.
• Spend protection: each request is priced first (quotes are free), expensive ones need a tap on Confirm, and per-person and whole-bot daily limits are enforced.
• Private by default: nobody else can use it until you allow them.

SpicyAPI's catalogue includes uncensored models that add no content filter of their own, and the bot works with any model you pick. The law and SpicyAPI's content policy still apply to everything you generate. See Policy.

Commands

The names are deliberately not /image, /video or /chat, which other popular bots use, so this bot can share a group with them. In a Telegram group, reply to one of the bot's chat messages to keep talking to the character.

Before you start

• A computer or server that stays on, with Docker installed. (Or a Railway account, see below.)
• A SpicyAPI account with a balance. See Account setup and Billing.
• A Telegram account, to create the bot with BotFather.

Deploy with Docker Compose

git clone https://github.com/spicyapi-ai/spicyapi-bot.git
cd spicyapi-bot
cp .env.example .env

SPICY_API_KEY=sk-spicy-...
TELEGRAM_BOT_TOKEN=123456789:AA...
OWNER_ID=your-telegram-user-id

docker compose up -d

docker compose up -d --build
docker compose logs -f

To update later, run git pull && docker compose up -d --build.

Deploy on Railway

Railway can run the bot without a server of your own. There is no one-click template: you deploy from your own copy of the repository.

Keep the service at one replica: two copies polling the same Telegram token fight over updates. The bot needs no public domain and no open port.

Add Discord (optional)

Discord does not allow apps with age-restricted commands in its App Directory, so keep the bot private. .env.example also has DISCORD_MEDIA_IN_DMS, which is false by default: images and videos then work only in age-restricted server channels, not in direct messages.

Who can use it

Strangers who find the bot are told it is private and given their user ID to send you. Groups are ignored until listed in ALLOWED_CHAT_IDS; once a group is listed, every member of it can use the bot, within the daily limits. Telegram group IDs are negative, for example -1001234567890.

You operate this bot and are responsible for who you let use it. SpicyAPI's terms apply, including the regions SpicyAPI does not serve.

How spending works

1. Price first. Each image or video is quoted by SpicyAPI before anything happens. Quotes are free.
2. Hard ceiling. If a request could cost more than MAX_COST_PER_REQUEST_USD (default $1), it is refused. Nothing is charged.
3. Confirmation. If it could cost more than CONFIRM_ABOVE_USD (default $0.10), the bot shows the price with Confirm and Cancel buttons. Only the person who asked can confirm.
4. Daily limits. Each person may spend USER_DAILY_BUDGET_USD (default $1) per UTC day and the whole bot DAILY_BUDGET_USD (default $5). Generations still running count as spent until they finish, so several requests at once cannot slip past a limit. Owners are only bound by the whole-bot limit.
5. No double charges. Each request carries an idempotency key derived from the chat message or button tap, so a duplicated Telegram update or a double tap returns the task that already exists.
6. Results. Progress is shown by editing one message every few seconds. The result shows the actual charge and the task ID, which you can look up under Logs in the console.

An accepted generation cannot be cancelled. Successful runs are charged; ordinary failures release the hold. Certain content refusals are charged only when the model page explicitly says so. See Billing.

Use a capped key

The bot keeps its own ledger in DATA_DIR/state.json. If that file is lost, the bot forgets what was spent today. The cap on the API key in the console is the limit that can never be lost, because SpicyAPI enforces it. Create a separate key for the bot, set a daily spend cap, and optionally allow only the models you want. When the cap is reached, the bot tells you the key has reached its spend cap.

Other useful settings:

Models and prices

Each person can change their models with /models. The operator sets the defaults:

The exact model ids are in .env.example; to switch, copy another id from the live catalog (in the character example below, MODEL_ID_FROM_CATALOG marks where such an id goes). Prices are from the public catalogue and can change; the bot always shows the live quote. Browse models at spicyapi.ai/models or see Models. For role-play, the roleplay leaderboard helps you choose a chat model.

Characters

Characters live in a JSON file (CHARACTERS_FILE, default characters/default.json, which has two example characters):

{
  "characters": [
    {
      "id": "mira",
      "name": "Mira",
      "system": "You are Mira, ... Never speak or act for {{user}}.",
      "greeting": "Welcome aboard, {{user}}!",
      "model": "MODEL_ID_FROM_CATALOG"
    }
  ]
}

• system is the character's instructions. greeting (optional) is their first line. model (optional) pins a chat model for this character.
• {{char}} and {{user}} are replaced with the character's name and the person's first name.
• Entries can also be Character Card V2 JSON, the format most character sites and SillyTavern export. The description, personality, scenario, example dialogue and first message are used.

With Docker, mount your own file and point the setting at it. In docker-compose.yml:

volumes:
  - ./my-characters.json:/app/characters/custom.json:ro

And in .env:

CHARACTERS_FILE=characters/custom.json

The bot remembers HISTORY_TURNS exchanges per conversation (default 20) and limits replies to CHAT_MAX_TOKENS tokens (default 2048). Reasoning models count their thinking toward that limit, so a very small value can leave no room for the answer. See Chat recipes for more on writing characters.

Photo uploads are off by default

By default, only images the bot generated can be animated. Turning photos of real people into videos is the main way bots like this get abused, and a person in a photo has not agreed to appear in your video.

If you set ALLOW_PHOTO_UPLOADS=true, anyone you allow can animate a photo they send. Only turn it on for people you trust, and only for photos of adults who agreed. When it is on, uploaded images are downloaded by the bot and stored with SpicyAPI. Telegram file links are never passed on, because they contain your bot token.

Privacy: what is stored where

Set RETENTION_SECONDS to ask SpicyAPI to delete results and prompts sooner than your account default.

In groups, results are hidden behind a spoiler (SPOILER_MEDIA, default groups; other values are always and never). /report forwards a message to the owner. Content that breaks SpicyAPI's rules can also be reported at spicyapi.ai/abuse.

Troubleshooting

Error codes are explained in Errors.