شروع سریع
مرشد API با SDKهای استاندارد OpenAI کار میکند. کافی است آدرس پایه را عوض کنید و کلید مرشد خود را بگذارید. بدون کارت ارزی و بدون VPN؛ شارژ ریالی از درگاه بانکی داخلی.
- ۱
کیفپول ریالی را با درگاه زرینپال شارژ کنید
- ۲
از بخش کلیدها یک کلید API بسازید
- ۳
آدرس پایه را به 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)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.morshed.ai/v1",
apiKey: "mk-xxxxxxxx", // از بخش کلیدها بسازید
});
const resp = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "سلام!" }],
});
console.log(resp.choices[0].message.content);curl https://api.morshed.ai/v1/chat/completions \
-H "Authorization: Bearer mk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "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
/v1/chat/completionsگفتگو (Chat Completions)
درخواست تکمیل گفتگو، کاملاً سازگار با OpenAI. با stream=true پاسخ بهصورت SSE استریم میشود و فراخوانی ابزار (tools/function calling) پشتیبانی میشود.
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
| model | string | بله | شناسهی مدل (اسلاگ کاتالوگ مرشد). |
| messages | array | بله | آرایهی پیامها با نقش و محتوا. |
| stream | boolean | خیر | با true پاسخ بهصورت SSE استریم میشود. |
| stream_options | object | خیر | با include_usage=true تکهی نهایی usage در استریم برگردانده میشود. |
| max_tokens | integer | خیر | سقف توکن خروجی. |
| tools | array | خیر | تعریف ابزارها برای 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)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.morshed.ai/v1",
apiKey: "mk-xxxxxxxx",
});
const resp = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "سلام!" }],
});
console.log(resp.choices[0].message.content);curl https://api.morshed.ai/v1/chat/completions \
-H "Authorization: Bearer mk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "سلام!"}]
}'| کد | HTTP | چه زمانی |
|---|---|---|
| invalid_api_key | ۴۰۱ | کلید نامعتبر یا غایب |
| rate_limit_exceeded | ۴۲۹ | عبور از سقف درخواست در دقیقه |
| invalid_request_error | ۴۰۰ | پارامتر لازم غایب یا نامعتبر |
| model_not_found | ۴۰۴ | مدل ناموجود، غیرفعال یا نامناسب این سرویس |
| insufficient_quota | ۴۰۲ | موجودی کیفپول یا سقف ماهانهی کلید |
| upstream_error | ۵۰۲ | خطای ارائهدهندهی مبدأ (بدون کسر هزینه) |
فیلد model در پاسخ همیشه به اسلاگ عمومی مرشد بازنویسی میشود.
/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)const models = await client.models.list(); for (const m of models.data) console.log(m.id);
curl https://api.morshed.ai/v1/models \ -H "Authorization: Bearer mk-xxxxxxxx"
| کد | HTTP | چه زمانی |
|---|---|---|
| invalid_api_key | ۴۰۱ | کلید نامعتبر یا غایب |
/v1/embeddingsامبدینگ (Embeddings)
بردار امبدینگ برای متن ورودی برمیگرداند. ورودی باید رشته یا آرایهای از رشتهها باشد؛ آرایهی توکن پشتیبانی نمیشود.
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
| model | string | بله | شناسهی مدل امبدینگ. |
| input | string | 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])const resp = await client.embeddings.create({
model: "text-embedding-3-small",
input: "متن نمونه برای بردارسازی",
});
console.log(resp.data[0].embedding.slice(0, 5));curl https://api.morshed.ai/v1/embeddings \
-H "Authorization: Bearer mk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-3-small",
"input": "متن نمونه برای بردارسازی"
}'| کد | HTTP | چه زمانی |
|---|---|---|
| invalid_api_key | ۴۰۱ | کلید نامعتبر یا غایب |
| rate_limit_exceeded | ۴۲۹ | عبور از سقف درخواست در دقیقه |
| invalid_request_error | ۴۰۰ | پارامتر لازم غایب یا نامعتبر |
| model_not_found | ۴۰۴ | مدل ناموجود، غیرفعال یا نامناسب این سرویس |
| insufficient_quota | ۴۰۲ | موجودی کیفپول یا سقف ماهانهی کلید |
| upstream_error | ۵۰۲ | خطای ارائهدهندهی مبدأ (بدون کسر هزینه) |
/v1/images/generationsتولید تصویر (Images)
از یک prompt متنی تصویر تولید میکند. پارامترهای size / quality / style پشتیبانی نمیشوند (قیمت واحد و ثابت).
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
| model | string | بله | شناسهی مدل تولید تصویر. |
| prompt | string | بله | توضیح متنی تصویر؛ خالی مجاز نیست. |
| n | integer | خیر | تعداد تصویر؛ عدد صحیح بین ۱ تا ۱۰ (پیشفرض ۱). |
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)const resp = await client.images.generate({
model: "gpt-image-1",
prompt: "یک گربهی فضانورد، سبک نقاشی آبرنگ",
n: 1,
});
console.log(resp.data[0].url);curl https://api.morshed.ai/v1/images/generations \
-H "Authorization: Bearer mk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-1",
"prompt": "یک گربهی فضانورد، سبک نقاشی آبرنگ",
"n": 1
}'| کد | HTTP | چه زمانی |
|---|---|---|
| invalid_api_key | ۴۰۱ | کلید نامعتبر یا غایب |
| rate_limit_exceeded | ۴۲۹ | عبور از سقف درخواست در دقیقه |
| invalid_request_error | ۴۰۰ | پارامتر لازم غایب یا نامعتبر |
| model_not_found | ۴۰۴ | مدل ناموجود، غیرفعال یا نامناسب این سرویس |
| insufficient_quota | ۴۰۲ | موجودی کیفپول یا سقف ماهانهی کلید |
| upstream_error | ۵۰۲ | خطای ارائهدهندهی مبدأ (بدون کسر هزینه) |
پارامترهای size / quality / style رد میشوند و خطای ۴۰۰ برمیگردانند.
/v1/audio/speechمتن به گفتار (Text-to-Speech)
متن را به صوت تبدیل میکند و بدنهی صوتی باینری (پیشفرض audio/mpeg) برمیگرداند. ورودی حداکثر ۴۰۹۶ کاراکتر است.
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
| model | string | بله | شناسهی مدل TTS. |
| input | string | بله | متن؛ خالی مجاز نیست، حداکثر ۴۰۹۶ کاراکتر. |
| voice | string | بله | نام صدا (مثل 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")const resp = await client.audio.speech.create({
model: "tts-1",
voice: "alloy",
input: "سلام! این صدای تولیدشده است.",
});
const buffer = Buffer.from(await resp.arrayBuffer());
await fs.promises.writeFile("speech.mp3", buffer);curl https://api.morshed.ai/v1/audio/speech \
-H "Authorization: Bearer mk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "tts-1",
"voice": "alloy",
"input": "سلام! این صدای تولیدشده است."
}' \
--output speech.mp3| کد | HTTP | چه زمانی |
|---|---|---|
| invalid_api_key | ۴۰۱ | کلید نامعتبر یا غایب |
| rate_limit_exceeded | ۴۲۹ | عبور از سقف درخواست در دقیقه |
| invalid_request_error | ۴۰۰ | پارامتر لازم غایب یا نامعتبر |
| model_not_found | ۴۰۴ | مدل ناموجود، غیرفعال یا نامناسب این سرویس |
| insufficient_quota | ۴۰۲ | موجودی کیفپول یا سقف ماهانهی کلید |
| upstream_error | ۵۰۲ | خطای ارائهدهندهی مبدأ (بدون کسر هزینه) |
/v1/audio/transcriptionsگفتار به متن (Transcriptions)
فایل صوتی را رونویسی میکند. درخواست multipart/form-data است و حجم فایل حداکثر ۲۵ مگابایت. قالب پاسخ json (پیشفرض)، verbose_json یا text.
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
| model | string (form field) | بله | شناسهی مدل STT. |
| file | file (form field) | بله | فایل صوتی؛ حداکثر ۲۵ مگابایت. |
| response_format | string (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)import fs from "node:fs";
const resp = await client.audio.transcriptions.create({
model: "whisper-1",
file: fs.createReadStream("audio.mp3"),
});
console.log(resp.text);curl https://api.morshed.ai/v1/audio/transcriptions \ -H "Authorization: Bearer mk-xxxxxxxx" \ -F model="whisper-1" \ -F file="@audio.mp3"
| کد | 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="")const stream = await client.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: "سلام!" }],
stream: true,
stream_options: { include_usage: true },
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}curl https://api.morshed.ai/v1/chat/completions \
-H "Authorization: Bearer mk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "سلام!"}],
"stream": true,
"stream_options": {"include_usage": true}
}'روی مسیر استریم، هدر هشدار موجودی کم افزوده نمیشود؛ اطلاعرسانی از کانال جانبی انجام میشود.
فراخوانی ابزار (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-warning | low_balance | موجودی کیفپول شما به آستانهی هشدار رسیده است؛ برای جلوگیری از قطع سرویس شارژ کنید. |
این هدر روی پاسخهای غیراستریم افزوده میشود.
هشدار امنیتی: کلید API را هرگز در کد سمت مرورگر قرار ندهید. کلید فقط برای استفادهی سمت سرور است.
قیمت مدلها (به تومان، با نرخ روز)
کاتالوگ مدلها بهزودی تکمیل میشود؛ سری بعد سر بزنید.