مستندات AI Workspace

شروع سریع

از طریق API هوش مصنوعی Workspace، به‌صورت برنامه‌نویسی با مدل‌های پیشرفته LLM تعامل داشته باشید. این API هم با API شرکت OpenAI (Chat Completions و Responses) و هم با API شرکت Anthropic (Messages) سازگار است؛ یعنی می‌توانید از کتابخانه‌ها و ابزارهای OpenAI و Anthropic استفاده کنید و فقط آدرس و کلید را عوض کنید.

آدرس پایه (Base URL)

تمام درخواست‌ها به این آدرس ارسال می‌شوند:

https://api.intelligence.sotoon.ir

احراز هویت

از کلید API خود برای احراز هویت استفاده کنید. کلیدهای خود را می‌توانید در بخش کلیدهای API مدیریت کنید.

کلید را در هدر Authorization ارسال کنید:

Authorization: Bearer YOUR_API_KEY

شناسه‌ی مدل را بردارید

مدل‌ها مرتب عوض می‌شوند، پس شناسه‌ی مدل را از صفحه‌ی «مدل‌ها» یا از خود API بردارید و دقیقاً همان‌طور که نوشته شده کپی کنید.

curl https://api.intelligence.sotoon.ir/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

اولین درخواست

در مثال‌ها MODEL_ID را با شناسه‌ی مدل عوض کنید.

cURL

curl -X POST 'https://api.intelligence.sotoon.ir/v1/chat/completions' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"model": "MODEL_ID",
"messages": [
{ "role": "user", "content": "پایتخت ایران کجاست؟" }
]
}'

Python (OpenAI SDK)

from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.intelligence.sotoon.ir/"
)
 
response = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "مکانیک کوانتومی را به زبان ساده توضیح دهید."}]
)
 
print(response.choices[0].message.content)

متن جواب در choices[0].message.content است. اگر خطا گرفتید، بخش «خطاها» را ببینید.

API

اندپوینت	کاربرد
`POST /v1/chat/completions`	گفتگو با مدل (قالب OpenAI Chat Completions)
`POST /v1/responses`	گفتگو با مدل (قالب OpenAI Responses)
`POST /v1/images/generations`	تولید تصویر
`GET /v1/models`	لیست مدل‌ها
`POST /v1/embeddings`	تبدیل متن به بردار
`POST /v1/messages`	گفتگو با مدل (قالب Anthropic Messages، برای Claude Code)

تکمیل چت (Chat Completions)

با استفاده از اندپوینت Chat Completions، به مدل‌ها پیام بفرستید و پاسخ‌های هوشمند دریافت کنید. نمونه‌ی درخواست را در «شروع سریع» ببینید.

پارامترهای کلیدی

model (الزامی): شناسه‌ی مدل، دقیقاً همان‌طور که در GET /v1/models یا صفحه‌ی مدل‌ها آمده است.
messages (الزامی): لیستی از اشیاء پیام (شامل role و content).
temperature: کنترل میزان خلاقیت. بازه‌ی مجاز بسته به مدل فرق می‌کند.
stream: برای دریافت پاسخ به‌صورت استریم، روی true تنظیم کنید.
max_tokens: سقف توکن پاسخ.
tools، tool_choice: فراخوانی ابزار (در ادامه توضیح داده شده است).

پارامترهای دیگر مثل مستندات OpenAI کار می‌کنند.

مدل‌های reasoning

این مدل‌ها قبل از جواب «فکر می‌کنند» و توکن‌های تفکر هم از max_tokens کم می‌شود. اگر max_tokens خیلی کوچک باشد، content خالی برمی‌گردد (با finish_reason برابر length) یا خطای 400 می‌گیرید. آن را بزرگ‌تر بگذارید یا ننویسید.

پاسخ‌های استریمینگ (Streaming)

پاسخ‌ها را به‌محض تولید، توکن‌به‌توکن دریافت کنید.

نمونه پایتون

stream = client.chat.completions.create(
    model="MODEL_ID",
    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="")

فراخوانی ابزار (Tool Calling)

مثل OpenAI کار می‌کند: ابزارها را در tools بفرستید و اگر مدل ابزار بخواهد، finish_reason برابر tool_calls است. همه‌ی مدل‌ها از ابزار پشتیبانی نمی‌کنند؛ اگر مدل ابزار را نپذیرد، خطای 400 می‌گیرید و باید مدل دیگری انتخاب کنید.

تولید تصویر

با مدل‌های تصویر، از روی متن تصویر تولید کنید. شناسه‌ی مدل تصویر را مثل مدل‌های دیگر از GET /v1/models بردارید (مثلاً google/gemini-3.1-flash-image).

اندپوینت: POST /v1/images/generations

نمونه درخواست (cURL)

curl -X POST 'https://api.intelligence.sotoon.ir/v1/images/generations' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"model": "google/gemini-3.1-flash-image",
"prompt": "یک شهر آینده‌نگر هنگام غروب خورشید"
}'

تصویر به‌صورت base64 در data[0].b64_json برمی‌گردد (فیلد url خالی است). برای ذخیره‌ی آن در یک فایل، خروجی درخواست بالا را با | به این دستور بدهید:

python3 -c 'import sys,json,base64; d=json.load(sys.stdin); open("image.png","wb").write(base64.b64decode(d["data"][0]["b64_json"]))'

پارامترهای دیگر (مثل size) بسته به مدل فرق می‌کند.

Embeddings

POST /embeddings متن را به بردار عددی تبدیل می‌کند. مدل‌های embedding در همان GET /v1/models هستند؛ برای این کار از مدل گفتگو استفاده نکنید.

curl https://api.intelligence.sotoon.ir/v1/embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "EMBEDDING_MODEL_ID", "input": "سلام دنیا" }'

بردار در data[0].embedding است.

Responses

POST /v1/responses قالب جدیدتر OpenAI است: به‌جای فهرست پیام‌ها، متن را در input می‌فرستید. ابزارها و کتابخانه‌هایی که از این قالب استفاده می‌کنند، فقط با عوض کردن آدرس و کلید وصل می‌شوند.

curl https://api.intelligence.sotoon.ir/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "MODEL_ID", "input": "سلام" }'

متن جواب در آیتم message به شکل output[].content[].text (از نوع output_text) می‌آید. اگر مدل reasoning باشد، قبل از آن یک آیتم reasoning هم هست. وضعیت درخواست در status است (مثلاً completed).

قالب Anthropic

POST /v1/messages برای مدل‌های مختلف (نه فقط Claude) کار می‌کند. در این قالب max_tokens الزامی است و پاسخ در content[0].text می‌آید.

curl https://api.intelligence.sotoon.ir/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{ "model": "MODEL_ID", "max_tokens": 1024,
        "messages": [{ "role": "user", "content": "سلام!" }] }'

مدل‌های OpenAI فعلاً روی /messages کار نمی‌کنند. مثلاً openai/gpt-6-luna خطای Unsupported parameter: 'max_tokens' می‌دهد. برای مدل‌های OpenAI از /chat/completions یا /responses استفاده کنید. همچنین بعضی مدل‌ها فیلدهای مخصوص Anthropic (مثل output_config) را رد می‌کنند و خطای 400 Unknown parameter می‌دهند.

خطاها

کد	دلیل رایج	چه کنم؟
401	کلید اشتباه یا باطل شده	کلید را دوباره کپی کنید. بعد از `Bearer` یک فاصله باشد.
400 `Invalid model name`	اسم مدل غلط است یا کلید شما به آن دسترسی ندارد	لیست مدل‌ها را دوباره بگیرید و اسم را دقیقاً کپی کنید.
400 `Unknown parameter`	پارامتری فرستاده‌اید که آن مدل نمی‌شناسد	آن پارامتر را حذف کنید.
400 با پیام «خروجی به سقف رسید»	`max_tokens` برای مدل reasoning خیلی کوچک است	`max_tokens` را بزرگ‌تر بگذارید یا ننویسید.
`Budget has been exceeded!`	بودجه‌ی workspace تمام شده است	از صفحه‌ی «مصرف» بودجه را افزایش دهید.
5xx	خطای موقت سرور یا ارائه‌دهنده‌ی مدل	با فاصله‌ی رو به افزایش دوباره بفرستید.
بدون پاسخ	مشکل اتصال	اینترنت و VPN را بررسی کنید. در curl گزینه‌ی `--max-time 60` بگذارید.

توصیه‌ها

مدیریت محدودیت نرخ (Rate Limits): منطق تلاش مجدد (Retry) با تأخیر نمایی را پیاده‌سازی کنید.
استریم پاسخ‌های طولانی: برای بهبود تجربه کاربری در خروجی‌های طولانی، از استریمینگ استفاده کنید.
پایش هزینه‌ها: میزان مصرف توکن‌های خود را در داشبورد زیر نظر داشته باشید.
پنجره بافت (Context Window): به محدودیت توکن هر مدل توجه کنید تا از خطاهای قطع‌شدن متن جلوگیری شود.

اتصال ابزارهای برنامه‌نویسی

قدرت مدل‌های پیشرفته AI Workspace را مستقیماً به جریان کاری توسعه خود بیاورید.

اکوسیستم‌های پشتیبانی شده

AI Workspace را با ابزارهای کدنویسی محبوب خود یکپارچه کنید:

Claude Code: دستیار کدنویسی مبتنی بر ترمینال از Anthropic.
GitHub Copilot: برنامه‌نویس جفتی محبوب برای VS Code و سایر محیط‌های توسعه.
Cursor: ویرایشگر کد مبتنی بر هوش مصنوعی.
Codex CLI: دستیار کدنویسی مبتنی بر ترمینال از OpenAI.

با متصل کردن این ابزارها به API سازگار با OpenAI و Anthropic ما، به تمام مدل‌های AI Workspace مستقیماً در IDE یا ترمینال خود دسترسی پیدا می‌کنید.

قبل از شروع

کلید API: از بخش «کلیدهای API».
شناسه‌ی مدل (MODEL_ID): از صفحه‌ی مدل‌ها. ابزارهای برنامه‌نویسی همیشه ابزار (tools) می‌فرستند، پس مدلی انتخاب کنید که Tool Calling را پشتیبانی کند و context بزرگ داشته باشد.
آدرس پایه: https://api.intelligence.sotoon.ir/

Claude Code

Claude Code از طریق متغیرهای محیطی (Environment Variables) به AI Workspace متصل می‌شود. می‌توانید آن را با افزونه‌ی VS Code (ساده‌تر، بدون ترمینال) یا از ترمینال وصل کنید. هر دو روش بدون اشتراک Claude کار می‌کنند و هزینه بر اساس توکن محاسبه می‌شود.

۱. نصب

CLI را از طریق npm نصب کنید:

npm install -g @anthropic-ai/claude-code

یا در macOS و Linux:

curl -fsSL https://claude.ai/install.sh | bash

۲. احراز هویت

متغیرهای محیطی زیر را تنظیم کنید. به آدرس پایه مخصوص Claude Code توجه کنید (بدون / در انتها و بدون /v1).

macOS / Linux: این خطوط را به فایل .zshrc یا .bashrc خود اضافه کنید:

export ANTHROPIC_BASE_URL=https://api.intelligence.sotoon.ir
export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY
export ANTHROPIC_MODEL=MODEL_ID
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

سپس دستور source ~/.zshrc را اجرا کنید.

Windows (PowerShell):

$env:ANTHROPIC_BASE_URL="https://api.intelligence.sotoon.ir"
$env:ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
$env:ANTHROPIC_MODEL="MODEL_ID"
$env:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS="1"

متغیر CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS قابلیت‌های آزمایشی مخصوص Anthropic را خاموش می‌کند. بدون آن، مدل‌های غیر Claude خطای 400 می‌دهند.

۳. نحوه استفاده

Claude Code را با مدل دلخواه خود اجرا کنید:

claude --model MODEL_ID

داخل Claude Code دستور /status را بزنید تا آدرس، توکن و مدل را ببینید.

استفاده با افزونه‌ی VS Code (به‌جای ترمینال)

در Extensions، افزونه‌ی Claude Code (ناشر: Anthropic) را نصب کنید.
Cmd+Shift+P (در Windows: Ctrl+Shift+P) را بزنید و Preferences: Open User Settings (JSON) را انتخاب کنید. این بلوک را داخل آکولاد اصلی فایل اضافه کنید:

"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "https://api.intelligence.sotoon.ir" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "YOUR_API_KEY" },
  { "name": "ANTHROPIC_MODEL", "value": "MODEL_ID" },
  { "name": "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS", "value": "1" }
],
"claudeCode.disableLoginPrompt": true

فایل را ذخیره کنید، VS Code را کامل ببندید و دوباره باز کنید.

GitHub Copilot (از طریق VS Code)

برای استفاده از مدل‌های AI Workspace با GitHub Copilot، پیشنهاد می‌کنیم از افزونه OAI Compatible Provider for Copilot استفاده کنید.

۱. نصب افزونه

بخش Extensions را در VS Code باز کنید (Cmd+Shift+X / Ctrl+Shift+X).
عبارت «OAI Compatible Provider for Copilot» را جستجو و نصب کنید.

۲. تنظیم اندپوینت

Command Palette را باز کنید (Cmd+Shift+P / Ctrl+Shift+P).
دستور «OAICopilot: Open Configuration UI» را اجرا کنید.
در بخش Global Configuration: Base URL: عبارت https://api.intelligence.sotoon.ir/ را وارد کنید. API Key: کلید خود را از بخش کلیدهای API وارد کنید.
روی Save Global Configuration کلیک کنید.

۳. افزودن مدل

در بخش Provider Management، روی Add Provider کلیک کنید: ID: عبارت sotoon (یا هر نام دلخواه). Mode: گزینه OpenAI را انتخاب کنید.
در بخش Model Management، روی Add Model کلیک کنید: Display Name: شناسه‌ی مدل (MODEL_ID). Context Length: اندازه‌ی context همان مدل از صفحه‌ی مدل‌ها. اگر نداشتید، 128000 را بگذارید.

۴. فعال‌سازی در Copilot

در نوار کناری Copilot، روی منوی کشویی انتخاب مدل کلیک کنید.
گزینه Manage Models ← Add Model ← OAI-compatible را انتخاب کنید.
مدلی که تازه ساختید را انتخاب کنید.

نکته

در پنل چت، نوع جلسه (session type) باید روی Local باشد.

Cursor

Cursor Settings ← Models ← API Keys را باز کنید.
در بخش OpenAI، کلید API را وارد کنید.
Override OpenAI Base URL را روشن کنید و https://api.intelligence.sotoon.ir/ را بنویسید (بدون /chat/completions در انتها).
Add Custom Model را بزنید و MODEL_ID را وارد کنید. هر مدل را جداگانه اضافه کنید.
Verify را بزنید و در Chat مدل را انتخاب کنید.

نکته

کلید و آدرس AI Workspace جایگزین کلید OpenAI می‌شود.

Codex CLI

فایل ~/.codex/config.toml را باز کنید (اگر نبود بسازید):

model = "MODEL_ID"
model_provider = "sotoon"
 
[model_providers.sotoon]
name = "AI Workspace"
base_url = "https://api.intelligence.sotoon.ir/"
env_key = "SOTOON_API_KEY"
wire_api = "chat"

model_provider باید با اسم بخش [model_providers.…] یکی باشد. اسم‌های openai، ollama و lmstudio رزرو هستند.
اگر نسخه‌ی Codex شما فقط قالب Responses را می‌پذیرد، به‌جای "chat" مقدار wire_api = "responses" بگذارید.
بعد codex را اجرا کنید، یا برای یک بار codex --model MODEL_ID.

قیمت‌گذاری و بودجه

مدل قیمت‌گذاری

AI Workspace بر اساس مدل پرداخت به ازای مصرف (Pay-as-you-go) عمل می‌کند. هیچ هزینه اولیه یا حق اشتراکی وجود ندارد؛ شما تنها بابت آنچه استفاده می‌کنید، بر اساس هزینه واقعی مدل‌ها پرداخت می‌کنید.

نحوه کارکرد

هر مدل زبانی (LLM) قیمت‌گذاری خاص خود را دارد که می‌توانید جزئیات آن را در صفحه مدل‌ها مشاهده کنید. هزینه‌ها به این بخش‌ها تقسیم می‌شوند:

قیمت ورودی: هزینه به ازای هر یک میلیون توکن ورودی
قیمت خروجی: هزینه به ازای هر یک میلیون توکن خروجی
قیمت cache: هزینه‌ی توکن‌های cache، فقط برای مدل‌هایی که cache را پشتیبانی می‌کنند

توجه

محاسبه قیمت، چه از طریق رابط چت استفاده کنید و چه از طریق API، یکسان است و بر اساس میزان مصرف توکن انجام می‌شود.

مشاهده قیمت‌ها

به صفحه مدل‌ها بروید.
برای مشاهده جزئیات قیمت (دلار به ازای هر میلیون توکن) روی هر مدل کلیک کنید.

تعداد توکن‌های مصرفی را در فیلد usage هر پاسخ و در صفحه‌ی «مصرف» می‌بینید. چند نکته درباره‌ی توکن‌ها:

مدل‌های reasoning: توکن‌های «تفکر» جزو توکن‌های خروجی (completion_tokens) شمرده می‌شوند، پس یک پاسخ کوتاه هم می‌تواند خروجی بیشتری از انتظار مصرف کند.
توکن‌های cache: بعضی مدل‌ها بخش تکراری ورودی (مثلاً یک پرامپت سیستمی یا مکالمه‌ی بلند) را cache می‌کنند و این توکن‌ها با قیمت جدا حساب می‌شوند. بعضی مدل‌ها (مثل Claude) باید در درخواست cache_control بگذارید.
عدد «توکن‌ها» در صفحه‌ی «مصرف» همه‌ی توکن‌ها را با هم می‌شمارد (ورودی + cache + خروجی)، برای همین ممکن است از عددی که کنسول سازنده‌ی مدل نشان می‌دهد بیشتر باشد.

بودجه و پرداخت

بودجه: هر workspace بودجه‌ی جداگانه‌ی خود را دارد. (بودجه به فرد اختصاص داده نشده است و به workspace اختصاص داده شده است). هزینه‌ی توکن‌های مصرف شده از این بودجه کم می‌شود.
افزایش بودجه: هر workspace در شروع، ۵ دلار بودجه‌ی اولیه دارد که می‌توانید تا روزانه ۸۰ دلار از طریق صفحه‌ی «مصرف» و دکمه‌ی «افزایش بودجه» آن را افزایش دهید. در صورت نیاز به بودجه‌ی بیشتر، در کانال پشتیبانی مترموست به ما اطلاع دهید.
فاکتور: روز ۲۳ هر ماه (تقویم شمسی) فاکتور صادر می‌شود و مصرف از ۲۳ ماه قبل تا ۲۲ همان ماه را شامل می‌شود. مثلاً فاکتور ۲۳ مهر، مصرف ۲۳ شهریور تا ۲۲ مهر است.
نرخ تبدیل: هزینه‌ی دلاریِ مصرف به نرخ دلار روز ۲۳ام محاسبه می‌شود و فاکتور به ریال صادر می‌شود. ۱۰٪ مالیات بر ارزش افزوده به فاکتور اضافه می‌شود.

بهینه‌سازی هزینه

انتخاب مدل مناسب: برای کارهای ساده‌تر از مدل‌های کوچک‌تر و ارزان‌تر استفاده کنید.
محدود کردن طول پاسخ: با تنظیم پارامتر max_tokens، هزینه‌ها را کنترل کنید. برای مدل‌های reasoning عدد را خیلی کوچک نگذارید.
پایش مصرف: همواره میزان مصرف توکن‌های خود را زیر نظر داشته باشید.
بهینه‌سازی پرامپت‌ها: دستورات (Prompt) شفاف و مختصر، توکن و هزینه کمتری مصرف می‌کنند.

نیاز به راهنمایی دارید؟

می‌توانید از طریق کانال پشتیبانی در مترموست با ما در تماس باشید.

مستندات

📄 مستندات AI Workspace

شروع سریع

آدرس پایه (Base URL)

احراز هویت

شناسه‌ی مدل را بردارید

اولین درخواست

API

تکمیل چت (Chat Completions)

پارامترهای کلیدی

پاسخ‌های استریمینگ (Streaming)

فراخوانی ابزار (Tool Calling)

تولید تصویر

Embeddings

Responses

قالب Anthropic

خطاها

توصیه‌ها

اتصال ابزارهای برنامه‌نویسی

اکوسیستم‌های پشتیبانی شده

قبل از شروع

Claude Code

۱. نصب

۲. احراز هویت

۳. نحوه استفاده

استفاده با افزونه‌ی VS Code (به‌جای ترمینال)

GitHub Copilot (از طریق VS Code)

۱. نصب افزونه

۲. تنظیم اندپوینت

۳. افزودن مدل

۴. فعال‌سازی در Copilot

Cursor

Codex CLI

قیمت‌گذاری و بودجه

مدل قیمت‌گذاری

نحوه کارکرد

مشاهده قیمت‌ها

بودجه و پرداخت

بهینه‌سازی هزینه

نیاز به راهنمایی دارید؟

فهرست