# AICredits — Full Reference

> AICredits is a unified LLM API gateway. One OpenAI-compatible endpoint, one API key, 300+ models, INR billing via Razorpay/UPI. Built for developers in India who need Claude, GPT-4o, Gemini, DeepSeek, Mistral, Sarvam, and Flux — without an international card.

## Base URL

OpenAI-compatible clients:
https://api.aicredits.in/v1

Anthropic SDK clients:
https://api.aicredits.in

Use the bare `https://api.aicredits.in` base URL with Anthropic SDKs because they append `/v1/messages` internally. Using `https://api.aicredits.in/v1` with the Anthropic SDK can produce `/v1/v1/messages`.

## Authentication
API keys start with `sk-` and are passed as `Authorization: Bearer sk-...` headers.
Get a key at: https://aicredits.in/dashboard/keys

---

## Chat Completions

POST /v1/chat/completions
Authorization: Bearer sk-YOUR_KEY
Content-Type: application/json

{
  "model": "openai/gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}

### Python (OpenAI SDK)

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-YOUR_AICREDITS_KEY",
    base_url="https://api.aicredits.in/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```

### TypeScript (OpenAI SDK)

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-YOUR_AICREDITS_KEY",
  baseURL: "https://api.aicredits.in/v1",
});

const response = await client.chat.completions.create({
  model: "anthropic/claude-haiku-4-5-20251001",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);
```

### cURL

```bash
curl https://api.aicredits.in/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

---

## Streaming

```python
stream = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

---

## Embeddings

POST /v1/embeddings
Authorization: Bearer sk-YOUR_KEY
Content-Type: application/json

{
  "model": "text-embedding-3-small",
  "input": "The quick brown fox"
}

Returns a vector embedding (array of floats) for use in semantic search, RAG, classification, etc.

### Python

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-YOUR_AICREDITS_KEY",
    base_url="https://api.aicredits.in/v1"
)

result = client.embeddings.create(
    model="text-embedding-3-small",
    input="The quick brown fox"
)
vector = result.data[0].embedding   # list of 1536 floats
print(f"Dimensions: {len(vector)}")
```

### TypeScript

```typescript
const result = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: "The quick brown fox",
});
const vector = result.data[0].embedding;
```

### Supported Embedding Models

| Model ID | Provider | Dimensions | Notes |
|----------|----------|-----------|-------|
| text-embedding-3-small | OpenAI | 1536 | Best cost/quality ratio |
| text-embedding-3-large | OpenAI | 3072 | Highest quality |
| text-embedding-ada-002 | OpenAI | 1536 | Legacy |
| deepinfra/BAAI/bge-large-en-v1.5 | DeepInfra | 1024 | Open-source, cheap |
| deepinfra/BAAI/bge-m3 | DeepInfra | 1024 | Multilingual |
| deepinfra/intfloat/e5-large-v2 | DeepInfra | 1024 | Open-source |
| deepinfra/intfloat/multilingual-e5-large | DeepInfra | 1024 | Multilingual |

---

## Image Generation

POST /v1/images/generations
Authorization: Bearer sk-YOUR_KEY
Content-Type: application/json

{
  "model": "black-forest-labs/flux-1-schnell",
  "prompt": "A sunset over the Himalayas",
  "size": "1024x1024",
  "n": 1
}

Returns a base64-encoded image in OpenAI format.

### Python

```python
import base64
from openai import OpenAI
from pathlib import Path

client = OpenAI(
    api_key="sk-YOUR_AICREDITS_KEY",
    base_url="https://api.aicredits.in/v1"
)

response = client.images.generate(
    model="black-forest-labs/flux-1-schnell",
    prompt="A sunset over the Himalayas",
    size="1024x1024",
    n=1,
    response_format="b64_json"
)
img_bytes = base64.b64decode(response.data[0].b64_json)
Path("output.png").write_bytes(img_bytes)
```

### cURL

```bash
curl https://api.aicredits.in/v1/images/generations \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "black-forest-labs/flux-1-schnell",
    "prompt": "A sunset over the Himalayas",
    "size": "1024x1024",
    "n": 1
  }'
```

### Supported Image Models

| Model ID | Provider | Notes |
|----------|----------|-------|
| dall-e-3 / openai/dall-e-3 | OpenAI | DALL-E 3 |
| gpt-image-1 / openai/gpt-image-1 | OpenAI | Latest OpenAI image model |
| black-forest-labs/flux-1-schnell | DeepInfra | Fast, cheap Flux |
| black-forest-labs/flux-1-dev | DeepInfra | Higher quality Flux |
| black-forest-labs/flux-1.1-pro | DeepInfra | Best quality Flux |
| black-forest-labs/flux-2-dev | DeepInfra | Flux 2 Dev |
| black-forest-labs/flux-2-pro | DeepInfra | Flux 2 Pro |
| black-forest-labs/flux-2-max | DeepInfra | Flux 2 Max |
| black-forest-labs/flux-1-kontext-dev | DeepInfra | Image editing |
| google/gemini-2.5-flash-preview-image-generation | Google | Gemini image gen |
| google/imagen-4.0-generate-001 | Google | Google Imagen |

Flux models use formula-based pricing (per pixel, per step). See pricing docs.

---

## Audio — Text-to-Speech (TTS)

POST /v1/audio/speech
Authorization: Bearer sk-YOUR_KEY
Content-Type: application/json

{
  "model": "openai/tts-1",
  "input": "Hello, how are you today?",
  "voice": "alloy"
}

Returns raw audio bytes (mp3 by default, wav for Sarvam).

### Python

```python
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key="sk-YOUR_AICREDITS_KEY",
    base_url="https://api.aicredits.in/v1"
)

response = client.audio.speech.create(
    model="openai/tts-1",
    voice="alloy",
    input="Hello, how are you today?",
)
Path("speech.mp3").write_bytes(response.content)
```

### TypeScript

```typescript
import fs from "fs";

const response = await client.audio.speech.create({
  model: "openai/tts-1",
  voice: "alloy",
  input: "Hello, how are you today?",
});
const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync("speech.mp3", buffer);
```

### cURL

```bash
curl https://api.aicredits.in/v1/audio/speech \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/tts-1", "input": "Hello!", "voice": "alloy"}' \
  --output speech.mp3
```

### TTS Models

| Model ID | Provider | Voices | Output | Notes |
|----------|----------|--------|--------|-------|
| openai/tts-1 | OpenAI | alloy, echo, fable, onyx, nova, shimmer | mp3 | Fast |
| openai/tts-1-hd | OpenAI | alloy, echo, fable, onyx, nova, shimmer | mp3 | Higher quality |
| sarvam/bulbul-v3 | Sarvam AI | anushka, abhilash, arya, karun, priya, … | wav | Indian languages, ₹30/10K chars |
| sarvam/bulbul-v2 | Sarvam AI | anushka, abhilash, arya, karun, priya, … | wav | Indian languages, ₹15/10K chars |

---

## Audio — Sarvam TTS (Indian Languages)

Sarvam Bulbul is purpose-built for Indian language text-to-speech. Pass a BCP-47 language code in `language` and a speaker name in `voice`.

### Python

```python
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key="sk-YOUR_AICREDITS_KEY",
    base_url="https://api.aicredits.in/v1"
)

response = client.audio.speech.create(
    model="sarvam/bulbul-v3",
    voice="anushka",           # native Sarvam speaker name
    input="नमस्ते, आप कैसे हैं?",
    # extra_body passes Sarvam-specific params:
    extra_body={"language": "hi-IN"}
)
Path("speech.wav").write_bytes(response.content)
```

### cURL

```bash
curl https://api.aicredits.in/v1/audio/speech \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sarvam/bulbul-v3",
    "input": "नमस्ते, आप कैसे हैं?",
    "voice": "anushka",
    "language": "hi-IN"
  }' \
  --output speech.wav
```

### OpenAI Voice Aliases → Sarvam Speakers

| OpenAI voice | Sarvam speaker |
|-------------|----------------|
| alloy | anushka |
| echo | abhilash |
| fable | arya |
| onyx | karun |
| nova | priya |
| shimmer | shreya |

All native speakers: anushka, abhilash, manisha, vidya, arya, karun, hitesh, aditya, ritu, priya, neha, rahul, pooja, rohan, simran, kavya, amit, dev, ishita, shreya, ratan, varun, manan, sumit, roopa, kabir, aayan, shubh, ashutosh, advait, anand, tanya, tarun, sunny, mani, gokul, vijay, shruti, suhani, mohit, kavitha, rehan, soham, rupali

### Supported Language Codes (Sarvam)

| Code | Language |
|------|----------|
| hi-IN | Hindi |
| en-IN | English (India) |
| bn-IN | Bengali |
| gu-IN | Gujarati |
| kn-IN | Kannada |
| ml-IN | Malayalam |
| mr-IN | Marathi |
| od-IN | Odia |
| pa-IN | Punjabi |
| raj-IN | Rajasthani |
| ta-IN | Tamil |
| te-IN | Telugu |

---

## Audio — Speech-to-Text (STT / Transcription)

POST /v1/audio/transcriptions
Authorization: Bearer sk-YOUR_KEY
Content-Type: multipart/form-data (standard OpenAI Whisper)

### Python (Whisper)

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-YOUR_AICREDITS_KEY",
    base_url="https://api.aicredits.in/v1"
)

with open("audio.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(
        model="openai/whisper-1",
        file=f,
        language="en"    # optional BCP-47 code
    )
print(transcript.text)
```

### cURL (Whisper)

```bash
curl https://api.aicredits.in/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -F "model=openai/whisper-1" \
  -F "file=@audio.mp3" \
  -F "language=en"
```

### Python (Sarvam — Indian languages)

```python
with open("speech.wav", "rb") as f:
    transcript = client.audio.transcriptions.create(
        model="sarvam/saarika-v2.5",
        file=("speech.wav", f, "audio/wav"),
        language="hi-IN"   # Sarvam BCP-47 language code
    )
print(transcript.text)
```

### STT Models

| Model ID | Provider | Languages | Notes |
|----------|----------|-----------|-------|
| openai/whisper-1 | OpenAI | 99 languages | $0.006/min |
| deepinfra/openai/whisper-large-v3 | DeepInfra | 99 languages | Cheaper than OpenAI |
| deepinfra/openai/whisper-large-v3-turbo | DeepInfra | 99 languages | Faster, slightly cheaper |
| sarvam/saarika-v2.5 | Sarvam AI | 12 Indian languages | Best for Hindi/Indian languages |
| sarvam/saarika-v2 | Sarvam AI | 12 Indian languages | Legacy (routes to v2.5) |

---

## List Models

GET /v1/models

Returns all available models in OpenAI-compatible format.

```bash
curl https://api.aicredits.in/v1/models \
  -H "Authorization: Bearer sk-YOUR_KEY"
```

---

## Supported Models (popular subset)

### Chat

| Model ID | Provider | Notes |
|----------|----------|-------|
| openai/gpt-4o | OpenAI | Vision, general purpose |
| openai/gpt-4o-mini | OpenAI | Fast, cheap |
| openai/o3 | OpenAI | Reasoning |
| openai/o4-mini | OpenAI | Fast reasoning |
| anthropic/claude-sonnet-4-20250514 | Anthropic | Complex reasoning |
| anthropic/claude-haiku-4-5-20251001 | Anthropic | Fast, cheap Claude |
| anthropic/claude-opus-4-20250514 | Anthropic | Most capable Claude |
| google/gemini-2.0-flash-001 | Google | Fast multimodal |
| google/gemini-2.5-pro-preview | Google | High quality |
| deepseek/deepseek-chat | DeepSeek | Coding, very cheap |
| deepseek/deepseek-r1 | DeepSeek | Reasoning |
| mistral/mistral-large | Mistral | European provider |
| xai/grok-3 | xAI | Grok models |
| deepinfra/meta-llama/Meta-Llama-3.1-8B-Instruct | DeepInfra | Open-source, cheap |
| deepinfra/meta-llama/Meta-Llama-3.3-70B-Instruct-Turbo | DeepInfra | Open-source, 70B |

Full list: https://aicredits.in/models or GET /v1/models

---

## Model ID Format

Models follow `provider/model-name` format:
- openai/gpt-4o
- anthropic/claude-sonnet-4-20250514
- google/gemini-2.0-flash-001
- deepseek/deepseek-chat
- black-forest-labs/flux-1-schnell
- sarvam/bulbul-v3
- deepinfra/meta-llama/Meta-Llama-3.1-8B-Instruct

Short names (gpt-4o, gpt-4o-mini, claude-haiku-4-5, gemini-2.0-flash) also work and auto-route to the correct provider.

---

## Billing

Cost = provider USD price × live INR/USD forex rate × (1 + user markup %)
- Default markup: 5%
- Forex buffer: 5% above live rate
- Wallet currency: INR
- Top-up via: Razorpay (UPI, cards, net banking, wallets)
- Minimum top-up: ₹50
- Gateway fee: ~2.36% deducted on payment

### Sarvam pricing (INR-native, no forex conversion)
- Bulbul v3 TTS: ₹30 per 10,000 characters
- Bulbul v2 TTS: ₹15 per 10,000 characters
- Saarika v2.5 STT: ₹30–45 per hour (billed per second)

### Flux pricing (formula-based)
- flux-1-schnell: based on image WxH and inference steps
- flux-1-dev / flux-1.1-pro: per-image flat rate
See https://aicredits.in/docs/pricing for formulas.

---

## Rate Limits

Default limits per API key:
- 60 requests per minute (RPM)
- Concurrency: plan-dependent
- Per-key budget limit (optional)

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

---

## Auth API (for onboarding users)

### Signup
POST /api/auth/signup
{"email": "...", "password": "...", "name": "..."}
→ Returns user object + sets JWT cookie

### Login
POST /api/auth/login
{"email": "...", "password": "..."}
→ {"token": "eyJ..."}

### Get profile + balance
GET /api/auth/me
Authorization: Bearer <jwt>
→ {"user": {"balance": 150.75, "email": "...", ...}}

### Create API key
POST /api/api-keys
Authorization: Bearer <jwt>
{"name": "My Project", "rate_limit": 60, "budget": 0}
→ {"api_key": "sk-..."}  ← shown only once, save it

### List API keys
GET /api/api-keys
Authorization: Bearer <jwt>

### Transaction history
GET /api/billing/transactions?page=1&limit=25
Authorization: Bearer <jwt>

---

## LangChain Integration

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="openai/gpt-4o-mini",
    openai_api_key="sk-YOUR_KEY",
    openai_api_base="https://api.aicredits.in/v1"
)
```

---

## Vercel AI SDK

```typescript
import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const aicredits = createOpenAI({
  apiKey: "sk-YOUR_KEY",
  baseURL: "https://api.aicredits.in/v1",
});

const { text } = await generateText({
  model: aicredits("openai/gpt-4o-mini"),
  prompt: "Hello!",
});
```

---

## Community Integrations

All integrations use the same OpenAI-compatible base URL and API key:

```text
Base URL: https://api.aicredits.in/v1
API key: sk-YOUR_AICREDITS_KEY
```

| Tool | Guide | Use case |
|------|-------|----------|
| Open WebUI | https://aicredits.in/docs/community/open-webui | Self-hosted chat UI |
| LiteLLM | https://aicredits.in/docs/community/litellm | Proxy or OpenAI-compatible upstream |
| Dify | https://aicredits.in/docs/community/dify | Chatbots, RAG apps, workflows, agents |
| Flowise | https://aicredits.in/docs/community/flowise | Visual chatflows and agentflows |
| Langflow | https://aicredits.in/docs/community/langflow | Visual AI workflows |
| AnythingLLM | https://aicredits.in/docs/community/anythingllm | Local-first chat, agents, document workspaces |
| LibreChat | https://aicredits.in/docs/community/librechat | Self-hosted ChatGPT-style team UI |
| LobeChat | https://aicredits.in/docs/community/lobechat | Self-hosted chat and agents |
| OpenHands | https://aicredits.in/docs/community/openhands | Self-hosted coding agents and automations |
| Cline | https://aicredits.in/docs/community/cline | IDE and CLI coding agent |
| RAGFlow | https://aicredits.in/docs/community/ragflow | Document RAG with chat and embeddings |
| Onyx | https://aicredits.in/docs/community/onyx | Enterprise search, chat, agents, RAG |
| CrewAI | https://aicredits.in/docs/community/crewai | Multi-agent Python workflows |
| LlamaIndex | https://aicredits.in/docs/community/llamaindex | RAG and document agents |
| Roo Code | https://aicredits.in/docs/community/roo-code | VS Code coding agent |

---

## Tool / Function Calling

```python
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"}
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "What's the weather in Mumbai?"}],
    tools=tools,
    tool_choice="auto"
)
```

---

## Error Format

All errors follow OpenAI error format:

```json
{
  "error": {
    "message": "Insufficient balance",
    "type": "insufficient_balance",
    "code": "402"
  }
}
```

Common status codes:
- 400: Invalid request (bad model, missing fields)
- 401: Invalid or missing API key
- 402: Insufficient balance
- 429: Rate limit exceeded — retry after X-RateLimit-Reset
- 500/502: Provider error (retried automatically in fallback chain)

---

## Cookbook & Example Projects

Runnable examples at https://github.com/chetanrakheja/aicredits-cookbook — Python (TypeScript planned) using the same OpenAI-compatible base URL and API key as above.

| Recipe | What it demonstrates |
|--------|----------------------|
| Resume/JD Matcher | JSON-mode structured output, evidence-grounded scoring |
| Exam MCQ Generator | Rubric-based generation and evaluation |
| Multi-Model Eval Harness | Comparing cost/quality across models through one endpoint |

`PROJECT_IDEAS.md` in the repo lists further beginner-to-advanced project ideas (WhatsApp bots, RAG, audio pipelines, agents) for students and new AI engineers.

---

## Docs Index
- https://aicredits.in/docs/quickstart
- https://aicredits.in/docs/api-reference
- https://aicredits.in/docs/authentication
- https://aicredits.in/docs/models
- https://aicredits.in/docs/pricing
- https://aicredits.in/docs/rate-limits
- https://aicredits.in/docs/sdks
- https://aicredits.in/docs/audio
- https://aicredits.in/docs/streaming
- https://aicredits.in/docs/tool-calling
- https://aicredits.in/docs/image-generation
- https://aicredits.in/docs/semantic-caching
- https://aicredits.in/docs/guardrails
- https://aicredits.in/docs/provider-routing
- https://aicredits.in/docs/community/n8n
- https://aicredits.in/docs/community/langchain
- https://aicredits.in/docs/community/vercel-ai
- https://aicredits.in/docs/community/pydanticai
- https://aicredits.in/docs/community/anthropic-agents
- https://aicredits.in/docs/community/hermes-agent
- https://aicredits.in/docs/community/cursor
- https://aicredits.in/docs/community/continue
- https://aicredits.in/docs/community/aider
- https://aicredits.in/docs/community/open-webui
- https://aicredits.in/docs/community/litellm
- https://aicredits.in/docs/community/dify
- https://aicredits.in/docs/community/flowise
- https://aicredits.in/docs/community/langflow
- https://aicredits.in/docs/community/anythingllm
- https://aicredits.in/docs/community/librechat
- https://aicredits.in/docs/community/lobechat
- https://aicredits.in/docs/community/openhands
- https://aicredits.in/docs/community/cline
- https://aicredits.in/docs/community/ragflow
- https://aicredits.in/docs/community/onyx
- https://aicredits.in/docs/community/crewai
- https://aicredits.in/docs/community/llamaindex
- https://aicredits.in/docs/community/roo-code
- https://aicredits.in/docs/community/langfuse
- https://aicredits.in/docs/community/openclaw