koko210Serve
a7f3a0a0ee
- Created miku-cli.py: Full-featured CLI for Miku bot API - Added interactive shell mode for continuous command execution - Implemented all API endpoints: status, mood, autonomous, DM, blocking, profile pictures - Consistent hyphenated command naming across shell and regular modes - Created API_REFERENCE.md: Complete API endpoint documentation - Created CLI_README.md: User guide with examples and usage instructions - Error handling and user-friendly output formatting
461 lines
8.0 KiB
Markdown
461 lines
8.0 KiB
Markdown
# Miku Discord Bot API Reference
|
|
|
|
The Miku bot exposes a FastAPI REST API on port 3939 for controlling and monitoring the bot.
|
|
|
|
## Base URL
|
|
```
|
|
http://localhost:3939
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### 📊 Status & Information
|
|
|
|
#### `GET /status`
|
|
Get current bot status and overview.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"status": "online",
|
|
"mood": "neutral",
|
|
"servers": 2,
|
|
"active_schedulers": 2,
|
|
"server_moods": {
|
|
"123456789": "bubbly",
|
|
"987654321": "excited"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `GET /logs`
|
|
Get the last 100 lines of bot logs.
|
|
|
|
**Response:** Plain text log output
|
|
|
|
#### `GET /prompt`
|
|
Get the last full prompt sent to the LLM.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"prompt": "Last prompt text..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 😊 Mood Management
|
|
|
|
#### `GET /mood`
|
|
Get current DM mood.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"mood": "neutral",
|
|
"description": "Mood description text..."
|
|
}
|
|
```
|
|
|
|
#### `POST /mood`
|
|
Set DM mood.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"mood": "bubbly"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"new_mood": "bubbly"
|
|
}
|
|
```
|
|
|
|
#### `POST /mood/reset`
|
|
Reset DM mood to neutral.
|
|
|
|
#### `POST /mood/calm`
|
|
Calm Miku down (set to neutral).
|
|
|
|
#### `GET /servers/{guild_id}/mood`
|
|
Get mood for specific server.
|
|
|
|
#### `POST /servers/{guild_id}/mood`
|
|
Set mood for specific server.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"mood": "excited"
|
|
}
|
|
```
|
|
|
|
#### `POST /servers/{guild_id}/mood/reset`
|
|
Reset server mood to neutral.
|
|
|
|
#### `GET /servers/{guild_id}/mood/state`
|
|
Get complete mood state for server.
|
|
|
|
#### `GET /moods/available`
|
|
List all available moods.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"moods": {
|
|
"neutral": "😊",
|
|
"bubbly": "🥰",
|
|
"excited": "🤩",
|
|
"sleepy": "😴",
|
|
...
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 😴 Sleep Management
|
|
|
|
#### `POST /sleep`
|
|
Force Miku to sleep.
|
|
|
|
#### `POST /wake`
|
|
Wake Miku up.
|
|
|
|
#### `POST /bedtime?guild_id={guild_id}`
|
|
Send bedtime reminder. If `guild_id` is provided, sends only to that server.
|
|
|
|
---
|
|
|
|
### 🤖 Autonomous Actions
|
|
|
|
#### `POST /autonomous/general?guild_id={guild_id}`
|
|
Trigger autonomous general message.
|
|
|
|
#### `POST /autonomous/engage?guild_id={guild_id}`
|
|
Trigger autonomous user engagement.
|
|
|
|
#### `POST /autonomous/tweet?guild_id={guild_id}`
|
|
Trigger autonomous tweet sharing.
|
|
|
|
#### `POST /autonomous/reaction?guild_id={guild_id}`
|
|
Trigger autonomous reaction to a message.
|
|
|
|
#### `POST /autonomous/custom?guild_id={guild_id}`
|
|
Send custom autonomous message.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"prompt": "Say something funny about cats"
|
|
}
|
|
```
|
|
|
|
#### `GET /autonomous/stats`
|
|
Get autonomous engine statistics for all servers.
|
|
|
|
**Response:** Detailed stats including message counts, activity, mood profiles, etc.
|
|
|
|
#### `GET /autonomous/v2/stats/{guild_id}`
|
|
Get autonomous V2 stats for specific server.
|
|
|
|
#### `GET /autonomous/v2/check/{guild_id}`
|
|
Check if autonomous action should happen for server.
|
|
|
|
#### `GET /autonomous/v2/status`
|
|
Get autonomous V2 status across all servers.
|
|
|
|
---
|
|
|
|
### 🌐 Server Management
|
|
|
|
#### `GET /servers`
|
|
List all configured servers.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"servers": [
|
|
{
|
|
"guild_id": 123456789,
|
|
"guild_name": "My Server",
|
|
"autonomous_channel_id": 987654321,
|
|
"autonomous_channel_name": "general",
|
|
"bedtime_channel_ids": [111111111],
|
|
"enabled_features": ["autonomous", "bedtime"]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### `POST /servers`
|
|
Add a new server configuration.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"guild_id": 123456789,
|
|
"guild_name": "My Server",
|
|
"autonomous_channel_id": 987654321,
|
|
"autonomous_channel_name": "general",
|
|
"bedtime_channel_ids": [111111111],
|
|
"enabled_features": ["autonomous", "bedtime"]
|
|
}
|
|
```
|
|
|
|
#### `DELETE /servers/{guild_id}`
|
|
Remove server configuration.
|
|
|
|
#### `PUT /servers/{guild_id}`
|
|
Update server configuration.
|
|
|
|
#### `POST /servers/{guild_id}/bedtime-range`
|
|
Set bedtime range for server.
|
|
|
|
#### `POST /servers/{guild_id}/memory`
|
|
Update server memory/context.
|
|
|
|
#### `GET /servers/{guild_id}/memory`
|
|
Get server memory/context.
|
|
|
|
#### `POST /servers/repair`
|
|
Repair server configurations.
|
|
|
|
---
|
|
|
|
### 💬 DM Management
|
|
|
|
#### `GET /dms/users`
|
|
List all users with DM history.
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"users": [
|
|
{
|
|
"user_id": "123456789",
|
|
"username": "User#1234",
|
|
"total_messages": 42,
|
|
"last_message_date": "2025-12-10T12:34:56",
|
|
"is_blocked": false
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### `GET /dms/users/{user_id}`
|
|
Get details for specific user.
|
|
|
|
#### `GET /dms/users/{user_id}/conversations`
|
|
Get conversation history for user.
|
|
|
|
#### `GET /dms/users/{user_id}/search?query={query}`
|
|
Search user's DM history.
|
|
|
|
#### `GET /dms/users/{user_id}/export`
|
|
Export user's DM history.
|
|
|
|
#### `DELETE /dms/users/{user_id}`
|
|
Delete user's DM data.
|
|
|
|
#### `POST /dm/{user_id}/custom`
|
|
Send custom DM (LLM-generated).
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"prompt": "Ask about their day"
|
|
}
|
|
```
|
|
|
|
#### `POST /dm/{user_id}/manual`
|
|
Send manual DM (direct message).
|
|
|
|
**Form Data:**
|
|
- `message`: Message text
|
|
|
|
#### `GET /dms/blocked-users`
|
|
List blocked users.
|
|
|
|
#### `POST /dms/users/{user_id}/block`
|
|
Block a user.
|
|
|
|
#### `POST /dms/users/{user_id}/unblock`
|
|
Unblock a user.
|
|
|
|
#### `POST /dms/users/{user_id}/conversations/{conversation_id}/delete`
|
|
Delete specific conversation.
|
|
|
|
#### `POST /dms/users/{user_id}/conversations/delete-all`
|
|
Delete all conversations for user.
|
|
|
|
#### `POST /dms/users/{user_id}/delete-completely`
|
|
Completely delete user data.
|
|
|
|
---
|
|
|
|
### 📊 DM Analysis
|
|
|
|
#### `POST /dms/analysis/run`
|
|
Run analysis on all DM conversations.
|
|
|
|
#### `POST /dms/users/{user_id}/analyze`
|
|
Analyze specific user's DMs.
|
|
|
|
#### `GET /dms/analysis/reports`
|
|
Get all analysis reports.
|
|
|
|
#### `GET /dms/analysis/reports/{user_id}`
|
|
Get analysis report for specific user.
|
|
|
|
---
|
|
|
|
### 🖼️ Profile Picture Management
|
|
|
|
#### `POST /profile-picture/change?guild_id={guild_id}`
|
|
Change profile picture. Optionally upload custom image.
|
|
|
|
**Form Data:**
|
|
- `file`: Image file (optional)
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"status": "ok",
|
|
"message": "Profile picture changed successfully",
|
|
"source": "danbooru",
|
|
"metadata": {
|
|
"url": "https://...",
|
|
"tags": ["hatsune_miku", "...]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### `GET /profile-picture/metadata`
|
|
Get current profile picture metadata.
|
|
|
|
#### `POST /profile-picture/restore-fallback`
|
|
Restore original fallback profile picture.
|
|
|
|
---
|
|
|
|
### 🎨 Role Color Management
|
|
|
|
#### `POST /role-color/custom`
|
|
Set custom role color.
|
|
|
|
**Form Data:**
|
|
- `hex_color`: Hex color code (e.g., "#FF0000")
|
|
|
|
#### `POST /role-color/reset-fallback`
|
|
Reset role color to fallback (#86cecb).
|
|
|
|
---
|
|
|
|
### 💬 Conversation Management
|
|
|
|
#### `GET /conversation/{user_id}`
|
|
Get conversation history for user.
|
|
|
|
#### `POST /conversation/reset`
|
|
Reset conversation history.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"user_id": "123456789"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 📨 Manual Messaging
|
|
|
|
#### `POST /manual/send`
|
|
Send manual message to channel.
|
|
|
|
**Form Data:**
|
|
- `message`: Message text
|
|
- `channel_id`: Channel ID
|
|
- `files`: Files to attach (optional, multiple)
|
|
|
|
---
|
|
|
|
### 🎁 Figurine Notifications
|
|
|
|
#### `GET /figurines/subscribers`
|
|
List figurine subscribers.
|
|
|
|
#### `POST /figurines/subscribers`
|
|
Add figurine subscriber.
|
|
|
|
#### `DELETE /figurines/subscribers/{user_id}`
|
|
Remove figurine subscriber.
|
|
|
|
#### `POST /figurines/send_now`
|
|
Send figurine notification to all subscribers.
|
|
|
|
#### `POST /figurines/send_to_user`
|
|
Send figurine notification to specific user.
|
|
|
|
---
|
|
|
|
### 🖼️ Image Generation
|
|
|
|
#### `POST /image/generate`
|
|
Generate image using image generation service.
|
|
|
|
#### `GET /image/status`
|
|
Get image generation service status.
|
|
|
|
#### `POST /image/test-detection`
|
|
Test face detection on uploaded image.
|
|
|
|
---
|
|
|
|
### 😀 Message Reactions
|
|
|
|
#### `POST /messages/react`
|
|
Add reaction to a message.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"channel_id": "123456789",
|
|
"message_id": "987654321",
|
|
"emoji": "😊"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Error Responses
|
|
|
|
All endpoints return errors in the following format:
|
|
|
|
```json
|
|
{
|
|
"status": "error",
|
|
"message": "Error description"
|
|
}
|
|
```
|
|
|
|
HTTP status codes:
|
|
- `200` - Success
|
|
- `400` - Bad request
|
|
- `404` - Not found
|
|
- `500` - Internal server error
|
|
|
|
## Authentication
|
|
|
|
Currently, the API does not require authentication. It's designed to run on localhost within a Docker network.
|
|
|
|
## Rate Limiting
|
|
|
|
No rate limiting is currently implemented.
|