MayuAI — AI Automation That Actually Works

Developer Documentation

Everything you need to integrate MayuAI into your applications. Simple, fast, and reliable.

Getting Started

Overview

MayuAI provides a unified API to access multiple AI models from providers like OpenAI, Anthropic, Google, Groq, and more. All through a single, simple interface.

Quick Start

1. Create an Account

2. Get Your API Key

Log in to your Dashboard
Navigate to API Keys
Click "Create API Key"
Give it a name (e.g., "Production Key")
Important: Copy the full key immediately - it's only shown once!

3. Make Your First Request

See code examples in the API Reference section below.

Authentication

MayuAI supports two authentication methods:

1. API Key (Recommended)

Include your API key in the x-api-key header:

x-api-key: YOUR_API_KEY

2. JWT Bearer Token

Include your JWT token from login in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Note: API keys are recommended for production use as they can be rotated without affecting user sessions.

Base URL

https://api.mayuai.com/v1

For local development:
http://localhost:4000/v1

Understanding Credits

Credits are MayuAI's universal usage currency. Different tasks consume different amounts:

Chat completions - Credits vary by model complexity
Image generation - Credits vary by image size and quality
Vision analysis - Credits vary by image complexity
Embeddings - Low credit usage
TTS/STT - Medium credit usage

Credits are automatically deducted after each successful API call. Check your balance anytime:

curl -X GET https://api.mayuai.com/v1/credits/balance \
  -H "x-api-key: YOUR_API_KEY"

API Reference

Base URL

https://api.mayuai.com/v1

For local development:
http://localhost:4000/v1

Authentication

All authenticated endpoints require either:

JWT Bearer Token (from login)
```
Authorization: Bearer YOUR_JWT_TOKEN
```
API Key (recommended for production)
```
x-api-key: YOUR_API_KEY
```

Get your API key from the Dashboard.

Chat Completions

Unified Chat Endpoint

The unified chat endpoint automatically routes to the correct provider based on the model name.

Endpoint: POST /v1/chat

Request Body:

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, world!"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1000
}

cURL Example:

curl -X POST https://api.mayuai.com/v1/chat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello, world!"}
    ]
  }'

JavaScript Example:

const response = await fetch('https://api.mayuai.com/v1/chat', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [
      { role: 'user', content: 'Hello, world!' }
    ],
    temperature: 0.7,
    max_tokens: 1000,
  }),
});

const data = await response.json();
console.log(data);

Python Example:

import requests

response = requests.post(
    'https://api.mayuai.com/v1/chat',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'gpt-4o',
        'messages': [
            {'role': 'user', 'content': 'Hello, world!'}
        ],
        'temperature': 0.7,
        'max_tokens': 1000,
    }
)

print(response.json())

Provider-Specific Endpoint

Endpoint: POST /v1/ai/:provider/:model

Example: POST /v1/ai/openai/gpt-4o

Vision API

Vision capabilities are available through the chat endpoint by including image content in messages.

Request Body:

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
          }
        }
      ]
    }
  ]
}

JavaScript Example:

// Convert image to base64
const imageBase64 = await convertImageToBase64('image.jpg');

const response = await fetch('https://api.mayuai.com/v1/chat', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: 'What is in this image?' },
          {
            type: 'image_url',
            image_url: {
              url: `data:image/jpeg;base64,${imageBase64}`
            }
          }
        ]
      }
    ]
  }),
});

const data = await response.json();
console.log(data);

Image Generation

Endpoint: POST /v1/images/generate

Request Body:

{
  "model": "dall-e-3",
  "prompt": "A beautiful sunset over mountains",
  "n": 1,
  "size": "1024x1024",
  "quality": "standard",
  "style": "vivid"
}

cURL Example:

curl -X POST https://api.mayuai.com/v1/images/generate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A beautiful sunset over mountains",
    "size": "1024x1024"
  }'

Embeddings

Endpoint: POST /v1/embeddings

Request Body:

{
  "model": "text-embedding-3-small",
  "input": "The quick brown fox jumps over the lazy dog",
  "encoding_format": "float"
}

JavaScript Example:

const response = await fetch('https://api.mayuai.com/v1/embeddings', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'text-embedding-3-small',
    input: 'The quick brown fox jumps over the lazy dog',
  }),
});

const data = await response.json();
console.log(data.data[0].embedding); // Array of floats

Text-to-Speech (TTS)

Endpoint: POST /v1/tts

Request Body:

{
  "text": "Hello, this is a test of text-to-speech",
  "voice": "alloy",
  "model": "tts-1",
  "response_format": "mp3",
  "speed": 1.0
}

JavaScript Example:

const response = await fetch('https://api.mayuai.com/v1/tts', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Hello, world!',
    voice: 'alloy',
    model: 'tts-1',
    response_format: 'mp3',
  }),
});

const audioBlob = await response.blob();
const audioUrl = URL.createObjectURL(audioBlob);
// Use audioUrl in an <audio> element

Speech-to-Text (STT)

Endpoint: POST /v1/stt

Request Body:

{
  "audio": "base64_encoded_audio_data",
  "model": "whisper-1",
  "language": "en",
  "prompt": "Optional context text"
}

Python Example:

import requests
import base64

# Read and encode audio file
with open('audio.mp3', 'rb') as f:
    audio_base64 = base64.b64encode(f.read()).decode('utf-8')

response = requests.post(
    'https://api.mayuai.com/v1/stt',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'audio': audio_base64,
        'model': 'whisper-1',
    }
)

data = response.json()
print(data['text'])

API Key Management

List API Keys

Endpoint: GET /v1/api-keys

curl -X GET https://api.mayuai.com/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Create API Key

Endpoint: POST /v1/api-keys

curl -X POST https://api.mayuai.com/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My API Key"}'

Regenerate API Key

Endpoint: POST /v1/api-keys/:keyId/regenerate

curl -X POST https://api.mayuai.com/v1/api-keys/key_abc123/regenerate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Revoke API Key

Endpoint: DELETE /v1/api-keys/:keyId

curl -X DELETE https://api.mayuai.com/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Credits

Get Credit Balance

Endpoint: GET /v1/credits/balance

curl -X GET https://api.mayuai.com/v1/credits/balance \
  -H "x-api-key: YOUR_API_KEY"

Models

List All Models

Endpoint: GET /v1/models

curl -X GET https://api.mayuai.com/v1/models

Rate Limits

Rate limits vary by plan:

Free Plan: 10 requests/minute, 1,000 requests/day
Starter Plan: 60 requests/minute, 10,000 requests/day
Pro Plan: 120 requests/minute, 50,000 requests/day
Developer Plan: 300 requests/minute, 200,000 requests/day

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200

When rate limit is exceeded, you'll receive a 429 Too Many Requests response.

Error Handling

Error Response Format

{
  "error": "error_code",
  "message": "Human-readable error message",
  "statusCode": 400
}

Common Error Codes

401 Unauthorized - Missing or invalid authentication
402 Payment Required - Insufficient credits
403 Forbidden - Model not available for your plan
404 Not Found - Endpoint or resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Language and Encoding

All text inputs should be UTF-8 encoded
Image data should be base64-encoded
Audio data should be base64-encoded
JSON requests must use Content-Type: application/json

Credits Guide

What are Credits?

Credits are MayuAI's universal usage currency. They provide a simple, unified way to pay for AI services across all providers and model types.

How Credits Work

Automatic Deduction

Credits are automatically deducted from your account after each successful API call. The amount deducted depends on:

Model complexity - More capable models consume more credits
Task type - Different tasks (chat, images, audio, vision) have different credit costs
Usage volume - Larger requests consume more credits

Credit Usage Examples

Task Type	Credit Efficiency
Mini models (GPT-4o mini, Gemini Flash)	Low usage
Standard models (GPT-4o, Claude Sonnet)	Medium usage
Large reasoning models (GPT-4, Claude Opus)	Higher usage
Standard images (512x512)	Low usage
HD images (1024x1024, 1792x1024)	Higher usage
Vision analysis	Medium to higher usage
Embeddings	Low usage
TTS/STT	Medium usage

Note: These are approximate ranges. Actual credit consumption may vary based on specific model capabilities and request complexity.

Checking Your Balance

You can check your credit balance at any time:

cURL:

curl -X GET https://api.mayuai.com/v1/credits/balance \
  -H "x-api-key: YOUR_API_KEY"

JavaScript:

const response = await fetch('https://api.mayuai.com/v1/credits/balance', {
  headers: {
    'x-api-key': 'YOUR_API_KEY',
  },
});

const data = await response.json();
console.log(`You have ${data.credits} credits remaining`);

Python:

import requests

response = requests.get(
    'https://api.mayuai.com/v1/credits/balance',
    headers={'x-api-key': 'YOUR_API_KEY'}
)

data = response.json()
print(f"You have {data['credits']} credits remaining")

Credit Balance in Responses

All API responses include your remaining credit balance:

{
  "choices": [...],
  "credits": {
    "used": 5,
    "remaining": 995
  }
}

Insufficient Credits

If you don't have enough credits for a request, you'll receive a 402 Payment Required error:

{
  "error": "insufficient_credits",
  "message": "Your account has no credits remaining. Please purchase credits to continue using the API.",
  "credits": 0,
  "required": 5
}

Getting More Credits

Subscription Plans

Monthly subscription plans include credits that refresh each month:

Starter: 1,000 credits/month
Pro: 3,000 credits/month
Developer: 10,000 credits/month

Pay-As-You-Go Packs

Purchase additional credits anytime with our credit packs:

Flexible amounts
No expiration
Instant activation

Visit the Pricing page to see available plans and credit packs.

Credits Never Expire

Credits purchased through pay-as-you-go packs never expire. Use them at your own pace.

Best Practices

Monitor your balance - Check credits regularly to avoid interruptions
Estimate usage - Use the cost estimation endpoint before large requests
Set up alerts - Configure low-credit notifications in your dashboard
Plan ahead - Purchase credits before you run out

Ready to Get Started?

Create your API key and start building with AI today.

Create API Key