شروع سریع

مرشد API با SDK‌های استاندارد OpenAI کار می‌کند. کافی است آدرس پایه را عوض کنید و کلید مرشد خود را بگذارید. بدون کارت ارزی و بدون VPN؛ شارژ ریالی از درگاه بانکی داخلی.

  1. ۱

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

  2. ۲

    از بخش کلیدها یک کلید API بسازید

  3. ۳

    آدرس پایه را به api.morshed.ai/v1 تغییر دهید

شروع سریع
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)

مرجع API

مستندات کامل هر سرویس برای توسعه‌دهنده‌ای که گِیت‌وی را یکپارچه می‌کند. همه‌چیز سازگار با OpenAI است؛ فقط base_url و کلید را عوض کنید.

احراز هویت

هر درخواست باید هدر Authorization با کلید مرشد داشته باشد. کلیدها با پیشوند mk- شروع می‌شوند و از مسیر داشبورد ← کلیدها ساخته می‌شوند. کلید فقط برای استفاده‌ی سمت سرور است.

Authorization: Bearer mk-xxxxxxxx

کلید نامعتبر یا غایب پاسخ ۴۰۱ با این بدنه برمی‌گرداند:

{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

آدرس پایه

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

https://api.morshed.ai/v1
POST/v1/chat/completions

گفتگو (Chat Completions)

درخواست تکمیل گفتگو، کاملاً سازگار با OpenAI. با 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-xxxxxxxx",
  "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۴۲۹عبور از سقف درخواست در دقیقه
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۴۲۹عبور از سقف درخواست در دقیقه
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": "gpt-image-1",
  "prompt": "یک گربه‌ی فضانورد، سبک نقاشی آبرنگ",
  "n": 1
}
نمونه‌ی پاسخ
{
  "created": 1234567890,
  "data": [
    { "url": "https://cdn.example.com/img/xxxxxxxx.png" }
  ]
}
نمونه‌ی کد
resp = client.images.generate(
    model="gpt-image-1",
    prompt="یک گربه‌ی فضانورد، سبک نقاشی آبرنگ",
    n=1,
)
print(resp.data[0].url)
خطاهای این سرویس
کدHTTPچه زمانی
invalid_api_key۴۰۱کلید نامعتبر یا غایب
rate_limit_exceeded۴۲۹عبور از سقف درخواست در دقیقه
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": "tts-1",
  "voice": "alloy",
  "input": "سلام! این صدای تولیدشده است."
}
نمونه‌ی پاسخ
# پاسخ بدنه‌ی صوتی باینری است (پیش‌فرض audio/mpeg)
# آن را مستقیماً در فایل ذخیره کنید، مثلاً speech.mp3
نمونه‌ی کد
resp = client.audio.speech.create(
    model="tts-1",
    voice="alloy",
    input="سلام! این صدای تولیدشده است.",
)
resp.write_to_file("speech.mp3")
خطاهای این سرویس
کدHTTPچه زمانی
invalid_api_key۴۰۱کلید نامعتبر یا غایب
rate_limit_exceeded۴۲۹عبور از سقف درخواست در دقیقه
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۴۲۹عبور از سقف درخواست در دقیقه
invalid_request_error۴۰۰پارامتر لازم غایب یا نامعتبر
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 بفرستید، یک تکه‌ی پایانی usage با choices خالی پیش از [DONE] دریافت می‌کنید.

قالب رویدادها
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 — تکه‌ی پایانی 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۴۰۲کلید به سقف هزینه‌ی ماهانه رسیده است.
rate_limit_exceeded۴۲۹عبور از سقف تعداد درخواست در دقیقه.
model_not_found۴۰۴مدل وجود ندارد، غیرفعال است یا با این سرویس سازگار نیست.
upstream_error۵۰۲ارائه‌دهنده‌ی مبدأ خطا داد؛ هزینه‌ای از شما کسر نمی‌شود.

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

هدرهای پاسخ

وقتی موجودی کیف‌پول شما رو به اتمام است، پاسخ‌ها یک هدر هشدار غیرمخرب به‌همراه دارند. بدنه‌ی پاسخ کاملاً سازگار با OpenAI باقی می‌ماند؛ کلاینت‌هایی که این هدر را نمی‌خوانند تحت تأثیر قرار نمی‌گیرند.

هدرمقدارمعنی
x-morshed-balance-warninglow_balanceموجودی کیف‌پول شما به آستانه‌ی هشدار رسیده است؛ برای جلوگیری از قطع سرویس شارژ کنید.

این هدر روی پاسخ‌های غیراستریم افزوده می‌شود.

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

قیمت مدل‌ها (به تومان، با نرخ روز)

فعلاً مدلی ارائه نشده است

کاتالوگ مدل‌ها به‌زودی تکمیل می‌شود؛ سری بعد سر بزنید.