API Reference

Overview

The Aventa AI API provides programmatic access to our AI tools platform. This documentation covers the available endpoints, authentication methods, and usage examples.

INFO

The API is currently in beta. Endpoints and parameters may change as we add more features to the platform.

Base URL

https://app.aventaproject.com/api

Authentication

All API requests require authentication using a Telegram ID or JWT token.

Headers

Content-Type: application/json
Authorization: Bearer <jwt-token>

Alternative Authentication

You can also pass authentication in the request body:

{
  "telegramId": "your-telegram-id",
  // ... other parameters
}

Endpoints

User Management

Get User Information

POST /users/me

Request Body:

{
  "telegramId": "123456789"
}

Response:

{
  "telegramId": "123456789",
  "username": "user123",
  "credits": 100,
  "xp": 250,
  "level": 5,
  "createdAt": "2025-01-01T00:00:00.000Z"
}

AI Image Generation

Generate Image

POST /generate-image

Request Body:

{
  "telegramId": "123456789",
  "prompt": "A beautiful sunset over mountains",
  "size": "1024x1024"
}

Response:

{
  "success": true,
  "image": {
    "url": "https://app.aventaproject.com/gen-images/generated-image.png",
    "prompt": "A beautiful sunset over mountains",
    "size": "1024x1024",
    "timestamp": "2025-01-01T00:00:00.000Z"
  },
  "creditsRemaining": 95
}

Credit Management

Check Balance

GET /users/balance?telegramId=123456789

Response:

{
  "credits": 100,
  "xp": 250,
  "level": 5
}

Add Credits (Admin Only)

POST /admin/credits/add

Headers:

Authorization: Bearer <admin-jwt-token>

Request Body:

{
  "telegramId": "123456789",
  "amount": 50,
  "reason": "Manual top-up"
}

Statistics

Get Platform Statistics

GET /stats/global

Response:

{
  "totalUsers": 1000,
  "totalImagesGenerated": 50000,
  "activeUsers24h": 150,
  "topUsers": [
    {
      "username": "user123",
      "xp": 5000,
      "level": 25
    }
  ]
}

Rate Limiting

API requests are rate limited to prevent abuse:

• General endpoints: 100 requests per 15 minutes
• Image generation: 20 requests per hour
• Admin endpoints: 10 requests per 15 minutes

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Error Responses

All errors follow a consistent format:

{
  "error": true,
  "message": "Description of the error",
  "code": "ERROR_CODE"
}

Common Error Codes

Code	Description
INSUFFICIENT_CREDITS	User doesn't have enough credits
INVALID_PROMPT	Image prompt is invalid or empty
RATE_LIMIT_EXCEEDED	Too many requests
UNAUTHORIZED	Missing or invalid authentication
USER_NOT_FOUND	Telegram ID not found

Webhooks (Coming Soon)

Webhook support for real-time notifications is planned for future releases.

SDK Support (Coming Soon)

Official SDKs for popular programming languages are in development:

• JavaScript/TypeScript
• Python
• Go
• PHP

Need Help?

• Join our Telegram community
• Use @AIAventaBot for testing AI features
• Check the Developer Guide for more examples
• Report issues on GitHub