Getting Started

API Overview

API Overview

Technical Specifications

Base URL

Code
 
https://beta.aimagicx.com/api/v1

Protocol

• HTTPS only - All API requests must use TLS 1.3
• REST architecture - Standard HTTP methods and status codes
• JSON format - Request and response bodies use JSON

API Versioning

• Current version: v1
• Version included in base URL path
• Breaking changes will increment version number
• Legacy versions supported for 12 months minimum

API Endpoints

Core Endpoints

Endpoint	Method	Description	Credit Cost
/chat	POST	Create AI chat completions	1 + tools used
/ai-image/generate	POST	Generate images from prompts	1 per image
/ai-image/logo	POST	Create professional logos	1 per logo
/models	GET	List available AI models	1
/tools	GET	List available AI tools	1

Account & Billing Endpoints

Endpoint	Method	Description	Credit Cost
/account	GET	Retrieve account details	1
/credits	GET	Get credit balance & history	1
/usage	GET	Detailed usage statistics	1
/overage/status	GET	Check overage configuration	1

Authentication

All API requests require authentication via API key in the Authorization header:

Code
 
Authorization: Bearer mgx-sk-your-api-key

See Authentication Guide for detailed security implementation.

Request Standards

Headers

Required headers for all requests:

Code
 
Authorization: Bearer mgx-sk-your-api-key
Content-Type: application/json
Accept: application/json

Request Body

• UTF-8 encoding required
• Maximum payload size: 10MB
• Nested objects supported up to 5 levels

Query Parameters

• URL encoding required for special characters
• Array parameters use param[]=value syntax
• Boolean values: true or false (lowercase)

Response Format

Success Response

Code(json)
 
{
  "success": true,
  "data": {
    // Endpoint-specific response data
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-01-10T12:00:00Z",
    "processingTime": 234
  }
}

Error Response

Code(json)
 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional context
    },
    "documentation": "https://docs.aimagicx.com/errors/ERROR_CODE"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-01-10T12:00:00Z"
  }
}

Response Headers

Standard Headers

All responses include these headers:

Code
 
X-Request-ID: Unique request identifier
X-Processing-Time: Request processing time in milliseconds
X-API-Version: Current API version

Rate Limit Headers

Code
 
X-RateLimit-Limit: Requests allowed per window
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when window resets
X-RateLimit-Window: Rate limit window duration (seconds)

Credit Usage Headers

Code
 
X-Credits-Used: Credits consumed by this request
X-Credits-Remaining: Credits remaining in current period
X-Credits-Reset: When monthly credits reset
X-Overage-Active: Whether overage billing is active
X-Overage-Rate: Current overage rate per credit

Rate Limiting

Rate Limit Tiers

Plan	Requests/Minute	Burst Limit	Concurrent Requests
API Starter	30	60	5
API Professional	120	240	20
Professional	60	120	10
Enterprise	Custom	Custom	Custom

Rate Limit Behavior

• Limits applied per API key
• 429 status code when exceeded
• Exponential backoff recommended
• Burst allowance for temporary spikes

Best Practices

Code(javascript)
 
// Example exponential backoff
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Error Codes

Client Errors (4xx)

Code	Description	Resolution
INVALID_REQUEST	Malformed request syntax	Check request format
UNAUTHORIZED	Invalid or missing API key	Verify API key
FORBIDDEN	Valid key but insufficient permissions	Check plan limits
NOT_FOUND	Requested resource doesn't exist	Verify endpoint URL
RATE_LIMIT_EXCEEDED	Too many requests	Implement backoff
INSUFFICIENT_CREDITS	Credit balance exhausted	Enable overage or add credits
PAYMENT_REQUIRED	Overage disabled, credits exhausted	Enable pay-as-you-go

Server Errors (5xx)

Code	Description	Resolution
INTERNAL_ERROR	Unexpected server error	Retry with backoff
SERVICE_UNAVAILABLE	Temporary service issue	Retry after delay
TIMEOUT	Request processing timeout	Reduce payload size

Idempotency

For critical operations, use idempotency keys to prevent duplicate processing:

Code
 
Idempotency-Key: unique-request-identifier

Idempotency keys are stored for 24 hours and guarantee exactly-once processing.

Streaming Responses

Chat completions support server-sent events (SSE) for real-time streaming:

Code
 
POST /api/v1/chat
Accept: text/event-stream

Stream format:

Code
 
data: {"token": "Hello", "index": 0}
data: {"token": " world", "index": 1}
data: [DONE]

Next Steps

• Authentication: Secure API key management
• Chat API: Conversational AI integration
• Image Generation: Visual content creation
• Usage & Billing: Monitor consumption and costs
• Code Examples: Implementation samples

---

For additional support, contact contact@aimagicx.com