مستندات

مستندات مرشد API

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

SDK سازگار
OpenAI
SDK سازگار
سرویس
۶
سرویس
آدرس پایه، یک کلید
۱
آدرس پایه، یک کلید
پرداخت از کیف پول
ریالی
پرداخت از کیف پول

شروع سریع در ۳ قدم

سه قدم کوتاه تا اولین پاسخ.

  1. کیف پول را شارژ کنید

    در پنل صفحهٔ «اعتبار و خرید» را باز کنید و با درگاه زرین‌پال اعتبار بخرید. هزینهٔ هر درخواست از همین اعتبار کم می‌شود.

    رفتن به «اعتبار و خرید»
    صفحهٔ «اعتبار و خرید» در پنل مرشد API با دکمهٔ «خرید اعتبار»
    صفحهٔ «اعتبار و خرید» در پنل
  2. یک کلید API بسازید

    در صفحهٔ «کلیدهای API» روی «ساخت کلید جدید» بزنید و یک نام بنویسید. کلید با mk- شروع می‌شود و فقط یک بار کامل نشان داده می‌شود؛ همان موقع کپی‌اش کنید و به کسی ندهید.

    رفتن به «کلیدهای API»
    تصویر متحرک: باز کردن صفحهٔ کلیدها، زدن «ساخت کلید جدید»، نوشتن نام و دیدن کلید ساخته‌شده
    ساخت کلید جدید، از اول تا آخر
  3. اولین درخواست را بفرستید

    در کد، آدرس پایه را https://api.morshed.ai/v1 بگذارید و کلید خودتان را جای mk-xxxxxxxx بنویسید. همین.

    from openai import OpenAI
    
    client = OpenAI(
        base_url="https://api.morshed.ai/v1",   # تنها تفاوت با OpenAI
        api_key="mk-xxxxxxxx",         # کلید مرشد، از بخش «کلیدها»
    )
    
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "سلام!"}],
    )
    print(resp.choices[0].message.content)
مدل gpt-4o-mini ارزان و سریع است و برای شروع عالی است. فهرست کامل مدل‌ها و قیمت هرکدام در صفحهٔ مدل‌ها آمده است.

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

مرشد API را به ابزاری که هر روز با آن کار می‌کنید وصل کنید. هر راهنما قدم‌به‌قدم و با تصویر است.

مرشد API چیست؟

مرشد API یک درگاه واحد برای مدل‌های هوش مصنوعی است که با SDK پایتون و جاوااسکریپت OpenAI و ابزارهایی که از Chat Completions استفاده می‌کنند سازگار است.

سازگار با OpenAI

با SDK پایتون و جاوااسکریپت OpenAI و ابزارهایی که Chat Completions دارند کار می‌کند. برای سرویس‌های فهرست‌شده در مرجع، فقط آدرس پایه و کلید را عوض می‌کنید.

همهٔ مدل‌ها، یک کلید

GPT، Claude، Gemini و صدها مدل دیگر، همه با یک کلید و یک آدرس.

پرداخت ریالی

کیف پول را با درگاه زرین‌پال شارژ می‌کنید. کارت ارزی و رمزارز لازم نیست.

بدون VPN

سرویس از داخل ایران در دسترس است و فیلترشکن لازم ندارید.

مهاجرت از OpenAI

فقط base_url و کلید را عوض کنید. پارامترها، استریم و فراخوانی ابزار همان است؛ شناسهٔ مدل را از صفحهٔ مدل‌ها بردارید.

# قبل: OpenAI
client = OpenAI(
    api_key="sk-...",
)

# بعد: مرشد (فقط همین دو خط)
client = OpenAI(
    base_url="https://api.morshed.ai/v1",
    api_key="mk-xxxxxxxx",
)

# برای سرویس‌های فهرست‌شده در مرجع، فقط آدرس پایه و کلید را عوض می‌کنید.

احراز هویت

هر درخواست باید هدر Authorization را با کلید مرشد شما داشته باشد. کلید را در پنل، صفحهٔ «کلیدهای API» می‌سازید.

Authorization: Bearer mk-xxxxxxxx
کلید را در کد سمت مرورگر نگذارید. کلید API فقط برای سمت سرور است. اگر در فرانت‌اند باشد، هرکسی می‌تواند از اعتبار شما خرج کند. کلید نامعتبر پاسخ ۴۰۱ می‌گیرد؛ کدهای خطا در بخش خطاها آمده است.

انتخاب مدل

مدل را با نام کوتاهش در فیلد model صدا می‌زنید، مثل gpt-4o-mini یا claude-haiku-4.5. فهرست زندهٔ مدل‌ها از GET /v1/models می‌آید.

سریع و کم‌هزینه

برای کارهای روزمره مدل‌های mini، flash و haiku بهترین نسبت قیمت به کیفیت را دارند.

دقیق و پیچیده

برای استدلال، کدنویسی و متن‌های حساس مدل‌های پرچم‌دار مثل نسخه‌های کامل GPT و Claude.

تخصصی

برای امبدینگ، تصویر و صدا مدل‌های اختصاصی هست. جزئیات در بخش مرجع سرویس‌ها.

کدام مدل برای کار شما بهتر است؟ آزمایشگاه مدل‌ها

صورتحساب ریالی

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

رزرو و تسویه

هر درخواست اول مبلغی را موقتاً رزرو (hold) می‌کند. بعد از پایان، فقط مصرف واقعی از کیف پول کم می‌شود.

هشدار موجودی کم

وقتی موجودی رو به اتمام است، پاسخ‌های غیراستریم هدر x-morshed-balance-warning: low_balance دارند. اگر موجودی از مبلغ رزرو لازم برای درخواست کمتر باشد، خطای ۴۰۲ برمی‌گردد؛ با max_tokens کوچک‌تر رزرو کمتر می‌شود.

قیمت مدل‌ها به تومان

مرجع سرویس‌ها

مستنداتِ کاملِ هر سرویس: نمونه‌ی درخواست، پاسخ، پارامترها، کدِ آماده و خطاهای هر سرویس. آدرس پایه‌ی همه‌ی سرویس‌ها https://api.morshed.ai/v1 است و قالب درخواست و پاسخ همان قالب OpenAI است.

POST/v1/chat/completions

گفتگو (Chat Completions)

درخواست تکمیل گفتگو، سازگار با OpenAI Chat Completions. با stream=true پاسخ به‌صورت SSE استریم می‌شود و فراخوانی ابزار (tools/function calling) پشتیبانی می‌شود.

پارامترها
نامنوعالزامیتوضیح
modelstringبلهشناسه‌ی مدل (اسلاگ کاتالوگ مرشد).
messagesarrayبلهآرایه‌ی پیام‌ها با نقش و محتوا.
streambooleanخیربا true پاسخ به‌صورت SSE استریم می‌شود.
stream_optionsobjectخیربا include_usage=true تکه‌ی نهایی usage در استریم برگردانده می‌شود.
max_tokensintegerخیرسقف توکن خروجی.
toolsarrayخیرتعریف ابزارها برای function calling (پاس‌ترو به مبدأ).
نمونه‌ی درخواست
POST https://api.morshed.ai/v1/chat/completions
Authorization: Bearer mk-xxxxxxxx
Content-Type: application/json

{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "سلام!"}]
}
نمونه‌ی پاسخ
{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "سلام! چطور می‌تونم کمک کنم؟" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 8, "completion_tokens": 12, "total_tokens": 20 }
}
نمونه‌ی کد
from openai import OpenAI

client = OpenAI(
    base_url="https://api.morshed.ai/v1",
    api_key="mk-xxxxxxxx",
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "سلام!"}],
)
print(resp.choices[0].message.content)
خطاهای این سرویس
کدHTTPچه زمانی
invalid_api_key۴۰۱کلید نامعتبر یا غایب
rate_limit_exceeded۴۲۹عبور از سقف ۶۰ درخواست در دقیقه برای هر کلید
null۴۰۰پارامتر لازم غایب یا نامعتبر (type: invalid_request_error)
model_not_found۴۰۴مدل ناموجود، غیرفعال یا نامناسب این سرویس
insufficient_quota۴۰۲موجودی کیف پول یا سقف هزینهٔ کلید (روزانه/هفتگی/ماهانه/کل)
upstream_error۵۰۲خطای ارائه‌دهنده‌ی مبدأ (بدون کسر هزینه)

فیلد model در پاسخ همیشه به اسلاگ عمومی مرشد بازنویسی می‌شود.

GET/v1/models

فهرست مدل‌ها (Models)

فهرست مدل‌های فعال کاتالوگ را در قالب استاندارد OpenAI برمی‌گرداند. نیازمند کلید معتبر است.

نمونه‌ی درخواست
GET https://api.morshed.ai/v1/models
Authorization: Bearer mk-xxxxxxxx
نمونه‌ی پاسخ
{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1234567890,
      "owned_by": "morshed"
    }
  ]
}
نمونه‌ی کد
models = client.models.list()
for m in models.data:
    print(m.id)
خطاهای این سرویس
کدHTTPچه زمانی
invalid_api_key۴۰۱کلید نامعتبر یا غایب
POST/v1/embeddings

امبدینگ (Embeddings)

بردار امبدینگ برای متن ورودی برمی‌گرداند. ورودی باید رشته یا آرایه‌ای از رشته‌ها باشد؛ آرایه‌ی توکن پشتیبانی نمی‌شود.

پارامترها
نامنوعالزامیتوضیح
modelstringبلهشناسه‌ی مدل امبدینگ.
inputstring | string[]بلهرشته یا آرایه‌ای از رشته‌ها؛ خالی مجاز نیست.
نمونه‌ی درخواست
POST https://api.morshed.ai/v1/embeddings
Authorization: Bearer mk-xxxxxxxx
Content-Type: application/json

{
  "model": "text-embedding-3-small",
  "input": "متن نمونه برای بردارسازی"
}
نمونه‌ی پاسخ
{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0021, -0.0135, 0.0074] }
  ],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 6, "total_tokens": 6 }
}
نمونه‌ی کد
resp = client.embeddings.create(
    model="text-embedding-3-small",
    input="متن نمونه برای بردارسازی",
)
print(resp.data[0].embedding[:5])
خطاهای این سرویس
کدHTTPچه زمانی
invalid_api_key۴۰۱کلید نامعتبر یا غایب
rate_limit_exceeded۴۲۹عبور از سقف ۶۰ درخواست در دقیقه برای هر کلید
null۴۰۰پارامتر لازم غایب یا نامعتبر (type: invalid_request_error)
model_not_found۴۰۴مدل ناموجود، غیرفعال یا نامناسب این سرویس
insufficient_quota۴۰۲موجودی کیف پول یا سقف هزینهٔ کلید (روزانه/هفتگی/ماهانه/کل)
upstream_error۵۰۲خطای ارائه‌دهنده‌ی مبدأ (بدون کسر هزینه)
POST/v1/images/generations

تولید تصویر (Images)

از یک prompt متنی تصویر تولید می‌کند. size / quality / style فقط برای اندازه‌هایی پذیرفته می‌شوند که برای آن مدل قیمت‌گذاری شده‌اند.

پارامترها
نامنوعالزامیتوضیح
modelstringبلهشناسه‌ی مدل تولید تصویر.
promptstringبلهتوضیح متنی تصویر؛ خالی مجاز نیست.
nintegerخیرتعداد تصویر؛ عدد صحیح بین ۱ تا ۱۰ (پیش‌فرض ۱).
نمونه‌ی درخواست
POST https://api.morshed.ai/v1/images/generations
Authorization: Bearer mk-xxxxxxxx
Content-Type: application/json

{
  "model": "flux-schnell",
  "prompt": "یک گربه‌ی فضانورد، سبک نقاشی آبرنگ",
  "n": 1
}
نمونه‌ی پاسخ
{
  "created": 1234567890,
  "data": [
    { "url": "https://cdn.example.com/img/xxxxxxxx.png" }
  ]
}
نمونه‌ی کد
resp = client.images.generate(
    model="flux-schnell",
    prompt="یک گربه‌ی فضانورد، سبک نقاشی آبرنگ",
    n=1,
)
print(resp.data[0].url)
خطاهای این سرویس
کدHTTPچه زمانی
invalid_api_key۴۰۱کلید نامعتبر یا غایب
rate_limit_exceeded۴۲۹عبور از سقف ۶۰ درخواست در دقیقه برای هر کلید
null۴۰۰پارامتر لازم غایب یا نامعتبر (type: invalid_request_error)
model_not_found۴۰۴مدل ناموجود، غیرفعال یا نامناسب این سرویس
insufficient_quota۴۰۲موجودی کیف پول یا سقف هزینهٔ کلید (روزانه/هفتگی/ماهانه/کل)
upstream_error۵۰۲خطای ارائه‌دهنده‌ی مبدأ (بدون کسر هزینه)

size / quality / style فقط برای اندازه‌هایی پذیرفته می‌شوند که برای آن مدل قیمت‌گذاری شده‌اند؛ مقدار دیگر خطای ۴۰۰ با فهرست اندازه‌های مجاز برمی‌گرداند.

POST/v1/audio/speech

متن به گفتار (Text-to-Speech)

متن را به صوت تبدیل می‌کند و بدنه‌ی صوتی باینری (پیش‌فرض audio/mpeg) برمی‌گرداند. ورودی حداکثر ۴۰۹۶ کاراکتر است.

پارامترها
نامنوعالزامیتوضیح
modelstringبلهشناسه‌ی مدل TTS.
inputstringبلهمتن؛ خالی مجاز نیست، حداکثر ۴۰۹۶ کاراکتر.
voicestringبلهنام صدا (مثل alloy).
نمونه‌ی درخواست
POST https://api.morshed.ai/v1/audio/speech
Authorization: Bearer mk-xxxxxxxx
Content-Type: application/json

{
  "model": "gemini-tts",
  "voice": "alloy",
  "input": "سلام! این صدای تولیدشده است."
}
نمونه‌ی پاسخ
# پاسخ بدنه‌ی صوتی باینری است (پیش‌فرض audio/mpeg)
# آن را مستقیماً در فایل ذخیره کنید، مثلاً speech.mp3
نمونه‌ی کد
resp = client.audio.speech.create(
    model="gemini-tts",
    voice="alloy",
    input="سلام! این صدای تولیدشده است.",
)
resp.write_to_file("speech.mp3")
خطاهای این سرویس
کدHTTPچه زمانی
invalid_api_key۴۰۱کلید نامعتبر یا غایب
rate_limit_exceeded۴۲۹عبور از سقف ۶۰ درخواست در دقیقه برای هر کلید
null۴۰۰پارامتر لازم غایب یا نامعتبر (type: invalid_request_error)
model_not_found۴۰۴مدل ناموجود، غیرفعال یا نامناسب این سرویس
insufficient_quota۴۰۲موجودی کیف پول یا سقف هزینهٔ کلید (روزانه/هفتگی/ماهانه/کل)
upstream_error۵۰۲خطای ارائه‌دهنده‌ی مبدأ (بدون کسر هزینه)
POST/v1/audio/transcriptions

گفتار به متن (Transcriptions)

فایل صوتی را رونویسی می‌کند. درخواست multipart/form-data است و حجم فایل حداکثر ۲۵ مگابایت. قالب پاسخ json (پیش‌فرض)، verbose_json یا text.

پارامترها
نامنوعالزامیتوضیح
modelstring (form field)بلهشناسه‌ی مدل STT.
filefile (form field)بلهفایل صوتی؛ حداکثر ۲۵ مگابایت.
response_formatstring (form field)خیریکی از json / verbose_json / text (پیش‌فرض json).
نمونه‌ی درخواست
POST https://api.morshed.ai/v1/audio/transcriptions
Authorization: Bearer mk-xxxxxxxx
Content-Type: multipart/form-data

model=whisper-1
file=@audio.mp3
نمونه‌ی پاسخ
{
  "text": "سلام! این یک نمونه‌ی رونویسی‌شده است."
}
نمونه‌ی کد
resp = client.audio.transcriptions.create(
    model="whisper-1",
    file=open("audio.mp3", "rb"),
)
print(resp.text)
خطاهای این سرویس
کدHTTPچه زمانی
invalid_api_key۴۰۱کلید نامعتبر یا غایب
rate_limit_exceeded۴۲۹عبور از سقف ۶۰ درخواست در دقیقه برای هر کلید
null۴۰۰پارامتر لازم غایب یا نامعتبر (type: invalid_request_error)
null۴۱۳فایل صوتی بزرگ‌تر از ۲۵ مگابایت (type: invalid_request_error)
model_not_found۴۰۴مدل ناموجود، غیرفعال یا نامناسب این سرویس
insufficient_quota۴۰۲موجودی کیف پول یا سقف هزینهٔ کلید (روزانه/هفتگی/ماهانه/کل)
upstream_error۵۰۲خطای ارائه‌دهنده‌ی مبدأ (بدون کسر هزینه)

استریم (SSE)

با stream=true پاسخ گفتگو به‌صورت Server-Sent Events برمی‌گردد: هر رویداد یک خط data: با یک تکه‌ی chat.completion.chunk است و جریان با data: [DONE] پایان می‌یابد. اگر stream_options.include_usage=true بفرستید، آخرین تکه پیش از [DONE] فیلد usage را دارد (ممکن است choices آن خالی نباشد).

قالب رویدادها
data: {"id":"chatcmpl-xxxxxxxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-xxxxxxxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"سلام"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxxxxxxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

# فقط با stream_options.include_usage=true: آخرین تکه پیش از [DONE] فیلد usage را دارد
data: {"id":"chatcmpl-xxxxxxxx","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":8,"completion_tokens":12,"total_tokens":20}}

data: [DONE]
نمونه‌ی کد
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "سلام!"}],
    stream=True,
    stream_options={"include_usage": True},  # تکه‌ی نهایی usage را برمی‌گرداند
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")

روی مسیر استریم، هدر هشدار موجودی کم افزوده نمی‌شود.

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

سرویس گفتگو از tools / function calling استاندارد OpenAI پشتیبانی می‌کند؛ آرایه‌ی tools به مبدأ پاس داده می‌شود و پاسخ می‌تواند tool_calls برگرداند.

نمونه‌ی کد
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "هوای تهران چطوره؟"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "آب‌وهوای یک شهر را برمی‌گرداند",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
)
print(resp.choices[0].message.tool_calls)

خطاها

همه‌ی خطاها از اسکیمای خطای سازگار با OpenAI پیروی می‌کنند: یک شیء error با فیلدهای message، type، code و param.

ساختار خطا
{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}
کدهای خطا
کدHTTPچه زمانی
invalid_api_key۴۰۱کلید API نامعتبر یا غایب است.
insufficient_quota۴۰۲موجودی کیف پول برای این درخواست کافی نیست.
monthly_cap_exceeded۴۰۲کلید به سقف هزینهٔ خود (روزانه/هفتگی/ماهانه/کل) رسیده است.
department_budget_exceeded۴۰۲دپارتمانِ این کلید به سقف بودجه‌اش رسیده است.
rate_limit_exceeded۴۲۹عبور از سقف ۶۰ درخواست در دقیقه برای هر کلید.
model_not_found۴۰۴مدل وجود ندارد، غیرفعال است یا با این سرویس سازگار نیست.
upstream_error۵۰۲ارائه‌دهنده‌ی مبدأ خطا داد؛ هزینه‌ای از شما کسر نمی‌شود.
internal_error۵۰۰خطای داخلی سرویس مرشد.

علاوه بر این‌ها، وقتی موجودی رو به اتمام است پاسخ‌های غیراستریم هدر هشدار غیرمخرب x-morshed-balance-warning: low_balance دارند.

اگر ارائه‌دهندهٔ مبدأ خطای ۴xx با بدنهٔ هم‌شکل OpenAI برگرداند، همان وضعیت و همان بدنه به شما می‌رسد.

مستندات و مرجع API · مرشد API