# راهنمای ManageIt AI

ManageIt AI یک درگاه واحد برای مدل‌های زبانی است که به برنامه‌نویس ایرانی اجازه می‌دهد با همان SDK همیشگی خود به ده‌ها مدل وصل شود و هزینه را به تومان بپردازد.

## ManageIt AI چیست؟

ManageIt AI یک درگاه (Gateway) برای مدل‌های هوش مصنوعی است: شما همان SDK یا ابزاری را که امروز استفاده می‌کنید نگه می‌دارید و فقط سه چیز را عوض می‌کنید: آدرس پایه (Base URL)، کلید API و نام مدل. بقیهٔ کد شما دست‌نخورده می‌ماند.

هزینهٔ هر درخواست بر اساس تعداد توکن‌های ورودی و خروجی حساب می‌شود و به تومان از کیف پول ManageIt شما کم می‌شود. نه قرارداد جداگانه لازم است، نه پرداخت ارزی.

هر مدل با نامی به شکل `manageit/<name>` شناخته می‌شود؛ مثلاً `manageit/claude-sonnet-5`. این‌که پشت هر مدل کدام ارائه‌دهنده قرار دارد، مسئولیت ManageIt است. شما فقط نام مدل را می‌فرستید و پاسخ را می‌گیرید.

## ساخت کلید API

برای کار با درگاه یک توکن دسترسی لازم دارید که از کنسول ManageIt ساخته می‌شود و فقط یک بار به شما نمایش داده می‌شود.

1. وارد کنسول ManageIt شوید: `https://console.stage.manageit.dev`
2. از منوی پروفایل، بخش «توکن‌های API» را باز کنید: `https://console.stage.manageit.dev/profile/tokens`
3. برای توکن یک نام انتخاب کنید. در نام فقط حروف لاتین، ارقام، نقطه و خط تیره مجاز است؛ مثلاً `my-app.v2`.
4. روی «ساخت توکن» بزنید.
5. توکن فقط یک بار نمایش داده می‌شود. همان لحظه آن را کپی کنید و در جای امنی نگه دارید. اگر آن را گم کردید، باید توکن تازه‌ای بسازید.

چند نکته دربارهٔ توکن‌ها:

- توکن را مثل رمز عبور نگه دارید. آن را در کد یا مخزن گیت قرار ندهید؛ از متغیر محیطی استفاده کنید.
- هر حساب می‌تواند حداکثر ده توکن داشته باشد.
- برای باطل کردن یک توکن، به همان صفحه برگردید و آن را حذف کنید. توکن حذف‌شده بلافاصله از کار می‌افتد.
- همین توکن با سایر سرویس‌های ManageIt هم کار می‌کند؛ لازم نیست برای هر سرویس توکن جداگانه بسازید.
- در بخش هوش مصنوعی کنسول (`https://console.stage.manageit.dev/ai/keys`) می‌توانید برای هر کلید سقف هزینه تعیین کنید یا آن را موقتاً متوقف کنید، بدون این‌که خود توکن را حذف کنید.

## استفادهٔ مستقیم از API

درگاه با هر زبان و هر ابزاری کار می‌کند، چون چیزی جز یک API سازگار با OpenAI و Anthropic نیست.

| مورد | مقدار |
| --- | --- |
| آدرس پایه برای فرمت OpenAI | `https://ai.stage.manageit.dev/api/v1` |
| آدرس پایه برای فرمت Anthropic | `https://ai.stage.manageit.dev/api` |
| آدرس پایه برای TypeSafe و laravel/ai | `https://ai.stage.manageit.dev/api/v1` |
| هدر احراز هویت | `Authorization: Bearer <token>` |
| هدر جایگزین (همان توکن) | `x-api-key: <token>` |

در مثال‌های زیر، به جای `YOUR_MANAGEIT_TOKEN` توکن خودتان را بگذارید.

### فهرست مدل‌ها

مدل‌های در دسترس و قیمت هر کدام را از این آدرس بگیرید. شناسهٔ مدل (`id`) دقیقاً همان چیزی است که باید در درخواست‌ها بفرستید.

```bash
curl https://ai.stage.manageit.dev/api/v1/models \
  -H "Authorization: Bearer YOUR_MANAGEIT_TOKEN"
```

### گفت‌وگو با فرمت OpenAI

مسیر `POST /api/v1/chat/completions` دقیقاً همان Chat Completions است که در OpenAI می‌شناسید:

```bash
curl https://ai.stage.manageit.dev/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_MANAGEIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "manageit/claude-sonnet-5",
    "messages": [
      {"role": "user", "content": "سلام! یک جملهٔ کوتاه دربارهٔ تهران بنویس."}
    ]
  }'
```

برای دریافت پاسخ به صورت جریانی (streaming) کافی است `stream` را `true` کنید. پاسخ به شکل رویدادهای SSE می‌آید و در انتهای آن تعداد توکن‌های مصرفی هم گزارش می‌شود:

```bash
curl -N https://ai.stage.manageit.dev/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_MANAGEIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "manageit/claude-sonnet-5",
    "stream": true,
    "messages": [
      {"role": "user", "content": "یک شعر دو بیتی دربارهٔ باران بگو."}
    ]
  }'
```

### فرمت Responses

اگر ابزار شما از فرمت جدیدتر OpenAI یعنی Responses استفاده می‌کند، مسیر `POST /api/v1/responses` در دسترس است:

```bash
curl https://ai.stage.manageit.dev/api/v1/responses \
  -H "Authorization: Bearer YOUR_MANAGEIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "manageit/claude-sonnet-5",
    "input": "سه پیشنهاد برای نام یک کافه بده."
  }'
```

### فرمت Anthropic

مسیر `POST /api/v1/messages` همان Messages API شرکت Anthropic است. SDK رسمی Anthropic خودش `/v1/messages` را به آدرس پایه اضافه می‌کند؛ به همین دلیل آدرس پایه برای این فرمت `https://ai.stage.manageit.dev/api` است، نه `https://ai.stage.manageit.dev/api/v1`.

```bash
curl https://ai.stage.manageit.dev/api/v1/messages \
  -H "x-api-key: YOUR_MANAGEIT_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "manageit/claude-sonnet-5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "سلام! خودت را در یک جمله معرفی کن."}
    ]
  }'
```

### تصمیم‌گیری با Jev

مدل‌های Jev از شرکت TypeSafe متن نمی‌نویسند؛ به پرسش‌های مشخص دربارهٔ یک وضعیت (`state`) پاسخ می‌دهند و برای هر پاسخ احتمال هم برمی‌گردانند. سه نوع پرسش وجود دارد: `noul` برای «آیا این شرط برقرار است؟»، `choice` برای «کدام گزینه؟» و `score` برای «روی این مقیاس کجاست؟». مسیر آن `POST /api/v1/systemone` است و همین درخواست در `POST /api/alpha/decisions` هم پذیرفته می‌شود:

```bash
curl https://ai.stage.manageit.dev/api/v1/systemone \
  -H "Authorization: Bearer YOUR_MANAGEIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "manageit/jev",
    "state": "پرداخت مشتری سه بار خطا داده و فروش ما متوقف شده است",
    "questions": {
      "is_urgent": {"type": "noul", "instructions": "آیا این پیام فوری است؟"},
      "team": {
        "type": "choice",
        "instructions": "کدام تیم باید رسیدگی کند؟",
        "criteria": {"billing": "پرداخت و صورت‌حساب", "technical": "خطا و قطعی"}
      }
    }
  }'
```

پاسخ برای هر پرسش، با همان نامی که فرستاده‌اید، یک جواب و احتمال‌های آن را دارد. این مسیر پاسخ جریانی ندارد و `stream` را نباید `true` کنید. هزینهٔ Jev فقط بر اساس توکن‌های ورودی حساب می‌شود. کتابخانهٔ TypeSafe و ارائه‌دهندهٔ `typesafe` در laravel/ai را کافی است با آدرس پایهٔ `https://ai.stage.manageit.dev/api/v1` و توکن ManageIt تنظیم کنید. خطاهای این مسیر به شکل `{"detail": ...}` برمی‌گردند که همان قالب TypeSafe است.

مدل `manageit/jev-router` (Jev Router) یک مدل گفت‌وگوست که برای هر درخواست خودش مدل مناسب را انتخاب می‌کند؛ از مسیر `POST /api/v1/chat/completions` در دسترس است و هزینهٔ هر درخواست به مدلی بستگی دارد که انتخاب کرده است.

### چند نکتهٔ مهم

- هر پاسخ درگاه یک هدر `x-request-id` دارد. اگر لازم شد با پشتیبانی تماس بگیرید، این شناسه را برای ما بفرستید تا درخواست شما را سریع پیدا کنیم.
- پاسخ‌های جریانی همان قالب SSE ارائه‌دهندهٔ اصلی را دارند، پس هیچ تغییری در سمت شما لازم نیست.
- معنی کدهای خطا و کاری که باید بکنید، در بخش «رفع مشکل» آمده است.

## استفاده در کد

اگر از کتابخانه‌های رسمی OpenAI یا Anthropic استفاده می‌کنید، فقط آدرس پایه و نام مدل را عوض کنید.

### Python با کتابخانهٔ openai

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://ai.stage.manageit.dev/api/v1",
    api_key="YOUR_MANAGEIT_TOKEN",
)

response = client.chat.completions.create(
    model="manageit/claude-sonnet-5",
    messages=[{"role": "user", "content": "سلام! خودت را معرفی کن."}],
)

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

برای پاسخ جریانی:

```python
stream = client.chat.completions.create(
    model="manageit/claude-sonnet-5",
    messages=[{"role": "user", "content": "یک داستان کوتاه بگو."}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

### Node.js با کتابخانهٔ openai

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ai.stage.manageit.dev/api/v1",
  apiKey: process.env.MANAGEIT_TOKEN,
});

const completion = await client.chat.completions.create({
  model: "manageit/claude-sonnet-5",
  messages: [{ role: "user", content: "سلام! خودت را معرفی کن." }],
});

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

### Python با کتابخانهٔ anthropic

```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://ai.stage.manageit.dev/api",
    api_key="YOUR_MANAGEIT_TOKEN",
)

message = client.messages.create(
    model="manageit/claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "سلام! خودت را معرفی کن."}],
)

print(message.content[0].text)
```

## استفاده در ابزارهای سازگار با DeepSeek و OpenAI

هر برنامه یا ایجنتی که تنظیم «DeepSeek» یا «OpenAI-compatible» دارد، با سه مقدار به ManageIt وصل می‌شود.

| فیلد | مقدار |
| --- | --- |
| Base URL | `https://ai.stage.manageit.dev/api/v1` |
| API Key | توکن ManageIt شما |
| Model | یک شناسهٔ `manageit/...` از فهرست مدل‌ها |

### کتابخانهٔ DeepSeek در Python

کتابخانهٔ DeepSeek همان کتابخانهٔ `openai` است که به آدرس DeepSeek وصل می‌شود. پس فقط آدرس پایه و نام مدل عوض می‌شود. برای مدل‌های استدلالی، متن استدلال در فیلد `reasoning_content` برمی‌گردد:

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://ai.stage.manageit.dev/api/v1",
    api_key="YOUR_MANAGEIT_TOKEN",
)

response = client.chat.completions.create(
    model="manageit/deepseek-v4-flash",
    messages=[{"role": "user", "content": "کدام بزرگ‌تر است: ۹٫۱۱ یا ۹٫۸؟"}],
)

message = response.choices[0].message
print("استدلال:", getattr(message, "reasoning_content", None))
print("پاسخ:", message.content)
```

### متغیرهای محیطی

بسیاری از ابزارهای خط فرمان و ایجنت‌ها تنظیمات خود را از متغیرهای محیطی می‌خوانند. بسته به این‌که ابزار شما کدام نام‌ها را می‌شناسد، یکی از این دو گروه را تنظیم کنید:

```bash
# ابزارهایی که تنظیم DeepSeek دارند
export DEEPSEEK_API_KEY="YOUR_MANAGEIT_TOKEN"
export DEEPSEEK_BASE_URL="https://ai.stage.manageit.dev/api/v1"

# ابزارهایی که تنظیم OpenAI دارند
export OPENAI_API_KEY="YOUR_MANAGEIT_TOKEN"
export OPENAI_BASE_URL="https://ai.stage.manageit.dev/api/v1"
```

بعد از تنظیم، نام مدل را در خود ابزار روی یک شناسهٔ `manageit/...` بگذارید.

### Claude Code

ابزار Claude Code با فرمت Anthropic کار می‌کند، پس آدرس پایه‌اش `https://ai.stage.manageit.dev/api` است. این متغیرها را در محیط خود تنظیم کنید و سپس Claude Code را اجرا کنید:

```bash
export ANTHROPIC_BASE_URL="https://ai.stage.manageit.dev/api"
export ANTHROPIC_AUTH_TOKEN="YOUR_MANAGEIT_TOKEN"
export ANTHROPIC_API_KEY=""
export ANTHROPIC_MODEL="manageit/claude-sonnet-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="manageit/claude-sonnet-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="manageit/claude-opus-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="manageit/claude-haiku-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="manageit/claude-sonnet-5"
```

`ANTHROPIC_API_KEY` را عمداً خالی بگذارید تا Claude Code سراغ کلید دیگری نرود. نام مدل‌ها را با فهرست مدل‌ها تطبیق دهید؛ مدل‌هایی که در بالا آمده‌اند فقط مثال هستند.

## هزینه‌ها و گزارش‌ها

قیمت هر مدل به تومان و برای هر یک میلیون توکن اعلام می‌شود، جداگانه برای ورودی و خروجی.

قیمت‌ها هم در فهرست مدل‌ها (`GET /api/v1/models`) آمده‌اند و هم در کنسول. مدل‌های مختلف قیمت‌های متفاوتی دارند، پس پیش از انتخاب مدل نگاهی به قیمت‌ها بیندازید.

هر درخواست بلافاصله پس از پایان محاسبه می‌شود، اما برداشت از کیف پول به صورت دسته‌ای انجام می‌شود: مبلغ چند درخواست جمع می‌شود و یک‌جا کم می‌شود. به همین دلیل ممکن است موجودی کیف پول با کمی تأخیر تغییر کند. همیشه به اندازهٔ کافی اعتبار در کیف پول نگه دارید تا درخواست‌ها با خطای `402` متوقف نشوند.

اگر موجودی کیف پول برای پاسخی به بلندی درخواست‌شده کافی نباشد، درگاه سقف طول پاسخ را به اندازه‌ای که موجودی پوشش می‌دهد پایین می‌آورد و ممکن است پاسخ زودتر از معمول تمام شود. در این حالت پاسخ هدر `x-manageit-output-capped` را دارد که مقدار آن سقف تازه بر حسب توکن است.

گزارش کامل مصرف را در بخش هوش مصنوعی کنسول (`https://console.stage.manageit.dev/ai`) می‌بینید: تعداد درخواست‌ها، توکن‌ها و هزینه، به تفکیک مدل، روز و کلید.

جزئیات تک‌تک درخواست‌ها تا ۹۰ روز در فهرست درخواست‌ها می‌ماند و پس از آن فقط در جمع روزانهٔ گزارش مصرف دیده می‌شود.

## رفع مشکل

هر خطای درگاه یک کد HTTP دارد که علت و راه حل آن مشخص است.

- `401`: توکن ارسال نشده یا اشتباه است: هدر `Authorization: Bearer <token>` را بررسی کنید و اگر توکن را حذف کرده‌اید، توکن تازه‌ای بسازید.
- `403`: این کلید اجازهٔ استفاده از درگاه هوش مصنوعی را ندارد یا متوقف شده است: وضعیت کلید را در `https://console.stage.manageit.dev/ai/keys` ببینید و در صورت نیاز آن را دوباره فعال کنید.
- `402`: موجودی کیف پول کافی نیست یا کلید به سقف هزینهٔ خود رسیده است: کیف پول را شارژ کنید یا سقف کلید را بالا ببرید.
- `404`: مدلی با این نام وجود ندارد: شناسهٔ دقیق مدل را از `GET /api/v1/models` بردارید و همان را بفرستید.
- `429`: تعداد درخواست‌های هم‌زمان یا درخواست در دقیقه بیشتر از حد مجاز است: چند ثانیه صبر کنید و دوباره تلاش کنید؛ هدر `Retry-After` می‌گوید چند ثانیه.
- `5xx`: مشکلی در سمت ما یا ارائه‌دهنده پیش آمده است: دوباره تلاش کنید و اگر تکرار شد، مقدار هدر `x-request-id` را برای پشتیبانی بفرستید.

اگر باز هم به مشکل خوردید، از طریق کنسول ManageIt با پشتیبانی در تماس باشید و شناسهٔ درخواست (`x-request-id`) را همراه پیام خود بفرستید.

## For AI agents

ManageIt AI is an OpenAI-compatible and Anthropic-compatible gateway to large language models, billed per token in Iranian Toman from a ManageIt wallet.

- OpenAI-style base URL (Chat Completions, Responses): `https://ai.stage.manageit.dev/api/v1`
- Anthropic-style base URL (Messages): `https://ai.stage.manageit.dev/api` (the SDK appends `/v1/messages`)
- Auth header: `Authorization: Bearer <token>`, or `x-api-key: <token>`
- Get a key: sign in at `https://console.stage.manageit.dev` and open `https://console.stage.manageit.dev/profile/tokens`; spend limits at `https://console.stage.manageit.dev/ai/keys`
- Endpoints: `GET /api/v1/models`, `GET /api/v1/models/{id}`, `POST /api/v1/chat/completions` (supports `stream: true`), `POST /api/v1/responses`, `POST /api/v1/messages`, `POST /api/v1/messages/count_tokens`, `POST /api/v1/systemone` and `POST /api/alpha/decisions` (TypeSafe's decisions API for Jev models: `state` plus typed `questions` in, `answers` with probabilities out; never streamed; errors as `{"detail": ...}`)
- Model naming: `manageit/<name>`; always send the exact `id` from `GET /api/v1/models`
- Pricing: each `/models` entry has a `pricing` block with `unit: per_1m_tokens` and a `toman` object giving the Toman price per one million tokens for input and output
- Response headers: every response carries `x-request-id`; `x-manageit-output-capped: <tokens>` means the output limit was lowered to what the wallet can pay for, so the answer may stop early
- Error codes: `401` bad or missing key, `403` key not allowed or paused, `402` insufficient credit or key spend limit, `404` model not found, `429` rate or concurrency limit (see `Retry-After`), `5xx` transient, retry and quote `x-request-id`
- This guide as raw Markdown: `https://ai.stage.manageit.dev/llms.txt` and `https://ai.stage.manageit.dev/llms-full.txt` (also `https://ai.stage.manageit.dev/docs.md`, or `GET /` with `Accept: text/markdown`)