راهنمای ManageIt AI

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

آخرین به‌روزرسانی:

متن خام راهنما در llms.txt

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) دقیقاً همان چیزی است که باید در درخواست‌ها بفرستید.

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

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

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

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 می‌آید و در انتهای آن تعداد توکن‌های مصرفی هم گزارش می‌شود:

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 در دسترس است:

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.

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 هم پذیرفته می‌شود:

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

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)

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

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

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

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 برمی‌گردد:

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)

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

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

# ابزارهایی که تنظیم 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 را اجرا کنید:

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)