AI Configuration
The TelegramBot API uses OpenRouter to access various AI language models. This guide covers API setup, model selection, prompt engineering, and tuning response behavior.OpenRouter Setup
OpenRouter provides unified access to multiple AI models through a single API.Create an account
Visit OpenRouter.ai and sign up for an account.
OpenRouter offers free models and paid premium models. Check the pricing page for current rates.
Generate API key
Navigate to the Keys section in your OpenRouter dashboard and create a new API key.Click Create Key and copy the generated key.
Add credits (optional)
For premium models, add credits to your account:
- Go to the Credits section
- Choose an amount to add
- Complete the payment
Free models like
tngtech/deepseek-r1t2-chimera:free don’t require credits.Model Selection
The default model is configured inapplication.yaml:
application.yaml:26-29
Available Models
OpenRouter provides access to numerous models. Popular options include:Free Models
Free Models
These models are free to use:
tngtech/deepseek-r1t2-chimera:free(default)google/gemini-2.0-flash-001:freemeta-llama/llama-3.1-8b-instruct:freemistralai/mistral-7b-instruct:free
Free models may have rate limits and lower priority during high demand.
Premium Models
Premium Models
Specialized Models
Specialized Models
Models optimized for specific tasks:
reasoningmodels - Better at logical reasoningcreativemodels - Enhanced creative writingcodemodels - Optimized for programming tasks
Changing the Model
To use a different model, updateapplication.yaml:
application.yaml:29
.env
System Prompt Configuration
The system prompt defines your bot’s personality and behavior.Default Prompt
The application includes a default “chaotic” Spanish AI personality:application.yaml:30
Customizing the Prompt
Define your own personality by settingAI_SYSTEM_PROMPT in .env:
Prompt Engineering Tips
Temperature Settings
Temperature controls response randomness and creativity.Configuration
application.yaml:31
.env:
.env
Temperature Guide
| Range | Behavior | Use Case |
|---|---|---|
0.0 - 0.3 | Very deterministic, focused, repetitive | Technical Q&A, factual information |
0.4 - 0.7 | Balanced, consistent, reliable | Customer support, documentation |
0.8 - 1.2 | Creative, varied, engaging | Conversation bots, creative writing |
1.3 - 1.7 | Highly creative, unpredictable | Entertainment, humor, brainstorming |
1.8 - 2.0 | Chaotic, experimental, random | Experimental bots, art generation |
The default value of
1.2 is optimized for the “chaotic AI” personality. Adjust based on your desired bot behavior.Max Tokens
Controls the maximum length of AI responses.Configuration
application.yaml:32
.env:
.env
Token Guidelines
What is a token?
What is a token?
Tokens are pieces of words. Roughly:
- 1 token ≈ 4 characters in English
- 1 token ≈ ¾ of a word
- 100 tokens ≈ 75 words
- “Hello world” = 2 tokens
- A typical paragraph = 50-100 tokens
Choosing the right value
Choosing the right value
Short responses (50-150 tokens):
- Quick replies
- Chat bot interactions
- Lower API costs
- Detailed explanations
- Customer support
- Balanced cost and quality
- Articles or essays
- Technical documentation
- Higher API costs
OpenRouter Configuration in Code
OpenRouterConfig
The configuration class sets up the REST client:src/main/java/com/acamus/telegrm/infrastructure/config/OpenRouterConfig.java
OpenRouterAdapter
The adapter implements the AI generation logic:src/main/java/com/acamus/telegrm/infrastructure/adapters/out/ai/OpenRouterAdapter.java
Testing AI Configuration
Send test messages
Message your Telegram bot with various prompts to test:
- Response quality
- Personality consistency
- Response length
- Creativity level
Error Handling
The adapter includes comprehensive error handling:src/main/java/com/acamus/telegrm/infrastructure/adapters/out/ai/OpenRouterAdapter.java:60-66
Common Errors
401 Unauthorized
401 Unauthorized
402 Payment Required
402 Payment Required
Cause: Insufficient credits for premium modelsSolution:
- Add credits to your OpenRouter account
- Switch to a free model temporarily
- Check usage at OpenRouter Dashboard
429 Rate Limit Exceeded
429 Rate Limit Exceeded
Cause: Too many requests in a short timeSolution:
- Reduce Telegram polling frequency
- Implement request queuing
- Upgrade OpenRouter plan for higher limits
500 Internal Server Error
500 Internal Server Error
Cause: OpenRouter service issueSolution:
- Check OpenRouter Status
- Retry after a few minutes
- Switch to a different model temporarily
Monitoring Usage and Costs
Track your AI usage to manage costs effectively:
- OpenRouter Dashboard: View real-time usage and costs
- Activity Log: See individual API calls and token usage
- Set Limits: Configure spending limits in your account
Usage Tracking
Visit the OpenRouter Activity Page to monitor:- Total API calls
- Token usage per request
- Cost per model
- Daily/monthly spending
Advanced Configuration
Custom Headers
The adapter sets custom headers for attribution:src/main/java/com/acamus/telegrm/infrastructure/config/OpenRouterConfig.java:22-23
Reasoning Support
Some models support reasoning output. To enable it, uncomment inOpenRouterAdapter.java:
src/main/java/com/acamus/telegrm/infrastructure/adapters/out/ai/OpenRouterAdapter.java:54-56
Reasoning shows the model’s thought process before generating the final answer. Only supported by specific models like
deepseek-reasoner.Configuration Summary
| Variable | Default | Purpose |
|---|---|---|
OPENROUTE_KEY | required | API authentication |
AI_SYSTEM_PROMPT | Chaotic Spanish AI | Bot personality |
AI_TEMPERATURE | 1.2 | Response creativity |
AI_MAX_TOKENS | 150 | Response length |
openrouter.model | tngtech/deepseek-r1t2-chimera:free | AI model selection |
openrouter.base-url | https://openrouter.ai/api/v1 | API endpoint |
Next Steps
Telegram Setup
Configure your Telegram bot
Environment Config
Review all configuration options
Development
Set up your development environment
Architecture
Understand the system architecture