# TamgaStudio API Guide

## Overview

TamgaStudio is a fully OpenAI-compatible API gateway. All endpoints match the OpenAI API format.
Base URL: `https://tamga.studio/api/v1`

## Authentication

All requests require a Bearer token in the Authorization header:

```
Authorization: Bearer tl-sk-xxxxxxxxxxxx
```

Get your API key from the dashboard at https://tamga.studio/dashboard/api-keys.php

## Credits System

- New accounts receive **$3.00 free credits**
- Each API call deducts from your credit balance based on actual token usage
- Rate limit: **20 requests per minute** per user
- Credit top-up is coming soon

## Endpoints

### Chat Completions
```
POST /api/v1/chat/completions
```
OpenAI-compatible chat completions. Supports streaming.
Request body:
```json
{
  "model": "openai/gpt-5",
  "messages": [{"role": "user", "content": "Hello!"}],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}
```

### Models List
```
GET /api/v1/models
```
Returns all available chat models with pricing.

## Coming Soon

The following endpoints are in development and not yet available:

- **Embeddings** — `POST /api/v1/embeddings`
- **Image Generation** — `POST /api/v1/images/generations`
- **Rerank** — `POST /api/v1/rerank`

Join the waitlist to get early access.

## Available Models (chat only)

### Anthropic
| Model ID | Context | Input $/1M tok | Output $/1M tok |
|---|---|---|---|
| anthropic/claude-haiku-4-5-20251001 | 200K | $1.00 | $5.00 |
| anthropic/claude-opus-4-20250514 | 200K | $15.00 | $75.00 |
| anthropic/claude-opus-4-1-20250805 | 200K | $15.00 | $75.00 |
| anthropic/claude-opus-4-5-20251101 | 200K | $5.00 | $25.00 |
| anthropic/claude-opus-4-6 | 200K | $5.00 | $25.00 |
| anthropic/claude-opus-4-7 | 1M | $5.00 | $25.00 |
| anthropic/claude-opus-4-8 | 1M | $5.00 | $25.00 |
| anthropic/claude-sonnet-4-20250514 | 200K | $3.00 | $15.00 |
| anthropic/claude-sonnet-4-5-20250929 | 200K | $3.00 | $15.00 |
| anthropic/claude-sonnet-4-6 | 200K | $3.00 | $15.00 |

### Google
| Model ID | Context | Input $/1M tok | Output $/1M tok |
|---|---|---|---|
| google/gemini-2.5-flash | 1M | $0.30 | $2.50 |
| google/gemini-2.5-flash-lite-preview-06-17 | 1M | $0.10 | $0.40 |
| google/gemini-2.5-pro | 1M | $1.25 | $10.00 |
| google/gemini-3-flash-preview | 1M | $0.50 | $3.00 |
| google/gemini-3.1-flash-lite-preview | 1M | $0.25 | $1.50 |
| google/gemini-3.1-pro-preview | 1M | $2.00 | $12.00 |
| google/gemini-3.5-flash | 1M | $1.50 | $9.00 |

### TamgaStudio
| Model ID | Context | Input $/1M tok | Output $/1M tok |
|---|---|---|---|
| tamgastudio/deepseek-v4-pro | 1M | $3.56 | $12.00 |
| tamgastudio/gemma-4-31B-it | 131K | $0.56 | $1.60 |
| tamgastudio/glm-5 | 200K | $3.60 | $12.80 |
| tamgastudio/gpt-oss-20b | 128K | $0.05 | $0.20 |
| tamgastudio/gpt-oss-120b | 128K | $0.10 | $0.40 |
| tamgastudio/kimi-k2.5 | 256K | $4.40 | $10.00 |
| tamgastudio/minimax-m2.5 | 196K | $1.00 | $4.80 |
| tamgastudio/nemotron-3-nano-omni-30b-a3b-reasoning | 256K | $1.00 | $2.00 |
| tamgastudio/nemotron-3-super-120b-a12b | 256K | $1.40 | $3.00 |
| tamgastudio/nvidia-nemotron-3-ultra-550b-a55b | 262K | $1.64 | $4.80 |

### OpenAI
| Model ID | Context | Input $/1M tok | Output $/1M tok |
|---|---|---|---|
| openai/gpt-3.5-turbo | 16K | $0.50 | $1.50 |
| openai/gpt-4 | 8K | $30.00 | $60.00 |
| openai/gpt-4-turbo | 128K | $10.00 | $30.00 |
| openai/gpt-4.1 | 1M | $2.00 | $8.00 |
| openai/gpt-4o | 128K | $2.50 | $10.00 |
| openai/gpt-5 | 400K | $1.25 | $10.00 |
| openai/gpt-5-mini | 400K | $0.25 | $2.00 |
| openai/gpt-5-nano | 400K | $0.05 | $0.40 |
| openai/gpt-5.2-2025-12-11 | 400K | $1.75 | $14.00 |
| openai/gpt-5.4-2026-03-05 | 1M | $2.50 | $15.00 |
| openai/gpt-5.4-mini-2026-03-17 | 400K | $0.75 | $4.50 |
| openai/gpt-5.4-nano-2026-03-17 | 400K | $0.25 | $1.25 |
| openai/gpt-5.5-2026-04-23 | 1M | $5.00 | $30.00 |
| openai/o3 | 200K | $2.00 | $8.00 |
| openai/o3-mini | 200K | $1.10 | $4.40 |

## Usage Examples

### cURL
```bash
curl https://tamga.studio/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

### Python (openai library)
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://tamga.studio/api/v1",
    api_key="YOUR_API_KEY"
)

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

### JavaScript
```javascript
const response = await fetch("https://tamga.studio/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "openai/gpt-5",
    messages: [{role: "user", content: "Hello!"}]
  })
});
const data = await response.json();
console.log(data.choices[0].message.content);
```

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

## Rate Limits
- **20 requests per minute** per API key
- HTTP 429 when exceeded

## Error Codes
| Code | HTTP Status | Description |
|---|---|---|
| invalid_api_key | 401 | Bad or expired API key |
| insufficient_credits | 402 | Credit balance is $0 |
| model_not_found | 404 | Unknown model ID |
| rate_limit_exceeded | 429 | Too many requests |
| missing_parameters | 400 | Required fields missing |
| coming_soon | 503 | Endpoint not yet available |