Bot para Telegram e Discord

O bot da SpicyAPI é um pequeno programa que você mesmo executa. Ele se conecta ao Telegram (e, se quiser, ao Discord) e permite que as pessoas que você autorizar gerem imagens, criem vídeos, transformem imagens em vídeos e conversem com personagens que você define. Tudo é pago com o seu próprio saldo da SpicyAPI, e cada requisição é cotada antes de qualquer cobrança.

O bot é gratuito e de código aberto (MIT) em github.com/spicyapi-ai/spicyapi-bot. Ele é privado por padrão: só você pode usá-lo até autorizar outras pessoas ou grupos.

O que o bot faz

• Imagens: /pic a lighthouse at dusk
• Vídeos: /vid waves rolling onto a beach at sunset
• Animate: toque em Animate sob qualquer imagem criada pelo bot, ou responda a ela com /animate <como ela deve se mover>.
• Chat com personagens: digite em um chat privado ou use /talk. As respostas chegam em streaming em uma única mensagem.
• Proteção de gastos: cada requisição é cotada antes (as cotações são gratuitas), as caras exigem um toque em Confirm, e os limites diários por pessoa e do bot inteiro são aplicados.
• Privado por padrão: ninguém mais pode usá-lo até você autorizar.

O catálogo da SpicyAPI inclui modelos sem censura, que não adicionam filtro de conteúdo próprio, e o bot funciona com qualquer modelo que você escolher. A lei e a política de conteúdo da SpicyAPI continuam valendo para tudo o que você gerar. Veja Política.

Comandos

Os nomes não são /image, /video nem /chat, que outros bots populares usam, de propósito: assim este bot pode dividir um grupo com eles. Em um grupo do Telegram, responda a uma das mensagens de chat do bot para continuar falando com o personagem.

Antes de começar

• Um computador ou servidor que fique ligado, com o Docker instalado. (Ou uma conta no Railway, veja abaixo.)
• Uma conta SpicyAPI com saldo. Veja Prepare sua conta e Cobrança.
• Uma conta no Telegram, para criar o bot com o BotFather.

Implante com 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

Para atualizar depois, execute git pull && docker compose up -d --build.

Implante no Railway

O Railway pode executar o bot sem que você precise de um servidor próprio. Não há template de um clique: você implanta a partir da sua própria cópia do repositório.

Mantenha o serviço em uma réplica: duas cópias consultando o mesmo token do Telegram disputam as atualizações. O bot não precisa de domínio público nem de porta aberta.

Adicione o Discord (opcional)

O Discord não permite apps com comandos restritos por idade no App Directory, então mantenha o bot privado. O .env.example também tem DISCORD_MEDIA_IN_DMS, que por padrão é false: imagens e vídeos então funcionam só em canais de servidor com restrição de idade, não em mensagens diretas.

Quem pode usar

Quem encontra o bot sem ser autorizado é informado de que ele é privado e recebe o próprio ID de usuário para enviar a você. Grupos são ignorados até serem listados em ALLOWED_CHAT_IDS; depois que um grupo é listado, todos os membros dele podem usar o bot, dentro dos limites diários. Os IDs de grupos do Telegram são negativos, por exemplo -1001234567890.

Você opera este bot e é responsável por quem deixa usá-lo. Os termos da SpicyAPI se aplicam, inclusive as regiões que a SpicyAPI não atende.

Como funciona o gasto

1. Preço primeiro. Cada imagem ou vídeo é cotado pela SpicyAPI antes de qualquer coisa acontecer. As cotações são gratuitas.
2. Teto rígido. Se uma requisição puder custar mais que MAX_COST_PER_REQUEST_USD (padrão $1), ela é recusada. Nada é cobrado.
3. Confirmação. Se puder custar mais que CONFIRM_ABOVE_USD (padrão $0,10), o bot mostra o preço com os botões Confirm e Cancel. Só quem fez o pedido pode confirmar.
4. Limites diários. Cada pessoa pode gastar USER_DAILY_BUDGET_USD (padrão $1) por dia UTC e o bot inteiro DAILY_BUDGET_USD (padrão $5). Gerações ainda em andamento contam como gastas até terminarem, então várias requisições ao mesmo tempo não conseguem escapar de um limite. Os donos só estão sujeitos ao limite do bot inteiro.
5. Sem cobrança duplicada. Cada requisição leva uma chave de idempotência derivada da mensagem do chat ou do toque no botão, então uma atualização duplicada do Telegram ou um toque duplo retorna a tarefa que já existe.
6. Resultados. O progresso é exibido editando uma mensagem a cada poucos segundos. O resultado mostra a cobrança real e o ID da tarefa, que você pode consultar em Logs no console.

Uma geração aceita não pode ser cancelada. Execuções bem-sucedidas são cobradas; falhas comuns liberam a retenção. Algumas recusas de conteúdo só são cobradas quando a página do modelo informa isso explicitamente. Veja Cobrança.

Use uma chave com limite

O bot mantém o próprio registro em DATA_DIR/state.json. Se esse arquivo for perdido, o bot esquece o que foi gasto hoje. O limite da chave de API no console é o que nunca se perde, porque a SpicyAPI o aplica. Crie uma chave separada para o bot, defina um limite de gasto diário e, se quiser, permita só os modelos desejados. Quando o limite é atingido, o bot avisa que a chave atingiu o limite de gasto.

Outras configurações úteis:

Modelos e preços

Cada pessoa pode mudar os próprios modelos com /models. O operador define os padrões:

Os ids exatos dos modelos estão no .env.example; para trocar, copie outro id do catálogo ao vivo (GET /api/v1/models; no exemplo de personagem abaixo, MODEL_ID_FROM_CATALOG marca onde um id desses entra). Os preços vêm do catálogo público e podem mudar; o bot sempre mostra a cotação em tempo real. Veja os modelos em spicyapi.ai/models ou consulte Catálogo de modelos e schemas. Para roleplay, o ranking de roleplay ajuda a escolher um modelo de chat.

Personagens

Os personagens ficam em um arquivo JSON (CHARACTERS_FILE, padrão characters/default.json, que tem dois personagens de exemplo):

{
  "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 são as instruções do personagem. greeting (opcional) é a primeira fala dele. model (opcional) fixa um modelo de chat para este personagem.
• {{char}} e {{user}} são substituídos pelo nome do personagem e pelo primeiro nome da pessoa.
• As entradas também podem ser JSON no formato Character Card V2, o formato que a maioria dos sites de personagens e o SillyTavern exportam. São usados a descrição, a personalidade, o cenário, o diálogo de exemplo e a primeira mensagem.

Com Docker, monte o seu próprio arquivo e aponte a configuração para ele. No docker-compose.yml:

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

E no .env:

CHARACTERS_FILE=characters/custom.json

O bot lembra HISTORY_TURNS trocas por conversa (padrão 20) e limita as respostas a CHAT_MAX_TOKENS tokens (padrão 2048). Modelos de raciocínio contam o pensamento nesse limite, então um valor muito pequeno pode não deixar espaço para a resposta. Veja Receitas de chat para mais sobre como escrever personagens.

O envio de fotos vem desativado

Por padrão, só as imagens geradas pelo bot podem ser animadas. Transformar fotos de pessoas reais em vídeos é a principal forma de abuso de bots como este, e a pessoa da foto não concordou em aparecer no seu vídeo.

Se você definir ALLOW_PHOTO_UPLOADS=true, qualquer pessoa autorizada por você pode animar uma foto que enviar. Ative apenas para pessoas de confiança e só para fotos de adultos que concordaram. Quando está ativado, as imagens enviadas são baixadas pelo bot e armazenadas na SpicyAPI. Os links de arquivos do Telegram nunca são repassados, porque contêm o token do seu bot.

Privacidade: o que fica guardado onde

Defina RETENTION_SECONDS para pedir à SpicyAPI que apague resultados e prompts antes do padrão da sua conta.

Em grupos, os resultados ficam ocultos atrás de um spoiler (SPOILER_MEDIA, padrão groups; os outros valores são always e never). O /report encaminha uma mensagem ao dono. Conteúdo que viola as regras da SpicyAPI também pode ser denunciado em spicyapi.ai/abuse.

Solução de problemas

Os códigos de erro estão explicados em Erros.