Mera AI Gateway Developer Reference

⚡ Quickstart

Issue an API Key in the dashboard, configure your environment, and send your first chat completion:

export API_KEY="sk-meraai-xxxxxxxxxxxxxxxx"

curl https://ai.ranjan.info/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "smart-auto-pilot",
    "messages": [
      {"role": "user", "content": "Explain asynchronous event loops simply."}
    ],
    "temperature": 0.7
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.ranjan.info/v1",
    api_key="sk-meraai-xxxxxxxxxxxxxxxx"
)

response = client.chat.completions.create(
    model="smart-auto-pilot",
    messages=[
        {"role": "system", "content": "You are a concise engineering tutor."},
        {"role": "user", "content": "Write a Python decorator for timing function execution."}
    ],
    temperature=0.3
)

print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://ai.ranjan.info/v1',
  apiKey: process.env.API_KEY || 'sk-meraai-xxxxxxxxxxxxxxxx',
});

const completion = await client.chat.completions.create({
  model: 'smart-auto-pilot',
  messages: [{ role: 'user', content: 'Generate a TypeScript union type for HTTP methods.' }],
});

console.log(completion.choices[0].message.content);

<?php
$payload = [
    'model' => 'smart-auto-pilot',
    'messages' => [
        ['role' => 'user', 'content' => 'Hello from PHP!']
    ]
];

$ch = curl_init('https://ai.ranjan.info/v1/chat/completions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk-meraai-xxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = json_decode(curl_exec($ch), true);
echo $response['choices'][0]['message']['content'];

🔑 Authentication

All gateway endpoints authenticate callers via HTTP Bearer token headers.

Authorization: Bearer sk-meraai-xxxxxxxxxxxxxxxx

🧠 Model Catalog GET/v1/models

Fetch all active direct models, aliases, and virtual tier profiles accessible to your key.

curl https://ai.ranjan.info/v1/models \
  -H "Authorization: Bearer $API_KEY"

{
  "object": "list",
  "data": [
    { "id": "smart-auto-pilot", "object": "model", "owned_by": "gateway-profile" },
    { "id": "fast-tier",        "object": "model", "owned_by": "gateway-profile" },
    { "id": "code-tier",        "object": "model", "owned_by": "gateway-profile" },
    { "id": "reasoning-tier",   "object": "model", "owned_by": "gateway-profile" },
    { "id": "gpt-4o",           "object": "model", "owned_by": "openai" },
    { "id": "claude-3-5-sonnet","object": "model", "owned_by": "anthropic" }
  ]
}

💬 Chat Completions POST/v1/chat/completions

Full OpenAI spec compatibility. Supports multi-turn conversations, tool calling, structured JSON output (`response_format`), temperature, and custom system instructions.

curl https://ai.ranjan.info/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a database architect."},
      {"role": "user", "content": "Compare SQLite WAL mode vs rollback journal."}
    ],
    "temperature": 0.5,
    "max_tokens": 1000
  }'

{
  "id": "chatcmpl-9x7K2m0aP8q",
  "object": "chat.completion",
  "created": 1725100000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Write-Ahead Logging (WAL) significantly improves concurrency..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 145,
    "total_tokens": 173
  }
}

🎭 Anthropic Messages API POST/v1/messages

Direct compatibility for tools and SDKs that speak Anthropic's native wire format (including Claude Code, Anthropic Python/TypeScript SDKs):

curl https://ai.ranjan.info/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet",
    "max_tokens": 1024,
    "system": "You are a senior Rust programmer.",
    "messages": [
      {"role": "user", "content": "Explain zero-cost abstractions."}
    ]
  }'

🌊 Real-Time Streaming

Pass "stream": true to receive Server-Sent Events (SSE) token by token as the upstream model generates them:

curl -N https://ai.ranjan.info/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fast-tier",
    "messages": [{"role": "user", "content": "Count from 1 to 5."}],
    "stream": true
  }'

data: {"id":"chatcmpl-1","choices":[{"delta":{"content":"1"}}]}
data: {"id":"chatcmpl-1","choices":[{"delta":{"content":", 2"}}]}
data: {"id":"chatcmpl-1","choices":[{"delta":{"content":", 3..."}}]}
data: [DONE]

✨ Smart Virtual Tiers & Auto-Pilot

Instead of hardcoding a specific proprietary model in your codebase, target high-level Virtual Tiers. The gateway dynamically evaluates latency, cost, and provider health, and transparently executes failover if an upstream is degraded.

📐 Vector Embeddings POST/v1/embeddings

Generate dense vector embeddings for semantic search, RAG pipelines, or clustering:

curl https://ai.ranjan.info/v1/embeddings \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Retrieval Augmented Generation with Vector Stores"
  }'

🎨 Image Generation POST/v1/images/generations

Generate photorealistic visuals, illustrations, and technical graphics via DALL-E, Flux, or Imagen with standard OpenAI SDK compatibility:

curl https://ai.ranjan.info/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "Isometric 3D enterprise server rack with glowing cyan fiber trails",
    "n": 1,
    "size": "1024x1024"
  }'

{
  "created": 1725100000,
  "data": [
    {
      "url": "https://storage.example.com/generated/img-9x7K2m0.png",
      "revised_prompt": "A 3D isometric view of an enterprise datacenter server rack..."
    }
  ],
  "model": "dall-e-3"
}

📊 Semantic Reranking POST/v1/rerank

Optimize Retrieval-Augmented Generation (RAG) by scoring and re-ordering candidate passages against a search query using cross-encoder models (Cohere, BGE-Reranker):

curl https://ai.ranjan.info/v1/rerank \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-english-v3.0",
    "query": "What is the key expiration policy?",
    "documents": [
      "Access keys can be revoked instantly in the security dashboard.",
      "Tokens expire automatically after 30 days unless configured otherwise.",
      "Rate limits reset every minute based on your plan quota."
    ],
    "top_n": 2
  }'

{
  "model": "rerank-english-v3.0",
  "results": [
    { "index": 1, "relevance_score": 0.982 },
    { "index": 0, "relevance_score": 0.421 }
  ]
}

🎙️ Audio Transcription & Speech POST/v1/audio/*

High-throughput multimodal audio endpoints for Whisper speech-to-text transcription and text-to-speech (TTS) voice generation:

curl https://ai.ranjan.info/v1/audio/transcriptions \
  -H "Authorization: Bearer $API_KEY" \
  -F file="@meeting-notes.mp3" \
  -F model="whisper-1"

curl https://ai.ranjan.info/v1/audio/speech \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Welcome to Mera AI universal gateway.",
    "voice": "alloy"
  }' \
  --output greeting.mp3

⚡ Response & Prompt Caching

🛡️ Content Safety & Guardrails

Enterprise safety policies can be enabled in Admin Settings to protect inbound and outbound traffic:

🌐 Live Web Search Grounding

When enabled in the chat studio or assistant settings, the gateway automatically queries configured search providers (Tavily, Brave, Serper, or Free Keyless) to inject fresh real-time web context into prompt responses.

💚 Health & Upstream Probes GET/v1/health

Public liveness and upstream provider health probe endpoint. Ideal for uptime monitoring, synthetic traffic checks, and load balancer readiness checks:

curl https://ai.ranjan.info/v1/health

{
  "status": "ok",
  "service": "Mera AI",
  "version": "1.0.0",
  "time": "2026-10-16T22:23:07+05:30",
  "providers": [
    { "name": "OpenAI", "status": "active", "latency_ms": 142 },
    { "name": "Anthropic", "status": "active", "latency_ms": 185 },
    { "name": "Groq", "status": "active", "latency_ms": 48 }
  ]
}

💻 IDE & SDK Configurations

Connect your developer environment to the gateway in seconds:

⚠️ Error Codes & Handling

All errors follow the standard OpenAI error envelope:

{
  "error": {
    "message": "Rate limit exceeded (60 rpm).",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}