مرجع Shawarma API: أدوات MCP وواجهة الويب

العناوين

المدخل	العنوان	لمين
خادم MCP	`https://shawarma.studio/mcp`	للوكلاء مثل Claude Code وCodex وCursor وClaude.ai وChatGPT. Streamable HTTP، وكل طلب POST واحد.
Web API	`https://shawarma.studio/v1`	لكودك أنت. JSON عبر HTTPS، ونفس الأدوات على شكل مسارات (routes).

الدخول والمفاتيح

كل طلب يحتاج الهيدر Authorization: Bearer <token>.
الـ token يا مفتاح API (يبدأ بـ shk_)، يا توكن دخول ياخذه Claude.ai أو ChatGPT لما تربطهم (OAuth، ويبدأ بـ sha_).
سوّ مفتاح من صفحة التطوير (Development) في قائمة حسابك. المفتاح يطلع لك مرة وحدة بس. تقدر تلغيه متى ما تبغى، ويوقف على طول.
المفتاح ما يقدر يغيّر الدفع والفواتير، ولا يحذف حسابك، ولا يسوّي مفاتيح ثانية.
بدون token، أو بواحد غلط، الرد يكون 401. والـ token اللي ما عنده الصلاحية (scope) اللي يحتاجها الطلب يجيه 403 insufficient_scope.

الصلاحية	يسمح بـ
`songs:read`	get_song، list_songs، النسخ، list_sounds، guide، check_code
`songs:write`	write_song، restore_version، share_song
`songs:compose`	make_song، change_song (من رصيد الذكاء الاصطناعي)
`audio:export`	export_audio (Pro)

الأدوات

كل أداة MCP، والوسائط حقها، ونفس الشي في API الويب.

`make_song`

ملحّن Shawarma يكتب لحن جديد من كلامك: الستايل، الجو، الآلات، السرعة، الطول. يحفظه ويرجّع الـ id والكود وملاحظة.

الوسيط	النوع	وش هو
`description` (مطلوب)	string	وش يكون اللحن، بالكلام.
`title`	string	اسم اللحن (الافتراضي: من الوصف).
`length_seconds`	number	طول اللحن تقريبًا بالثواني (من 5 إلى 600).
`wait_seconds`	number	كم ثانية ينتظر النتيجة قبل ما يكون الرد مهمة (job) (الافتراضي 40، والحد الأقصى 55).

API الويب: POST /v1/songs {description, title?, length_seconds?}

الباقة: رصيد الذكاء الاصطناعي (Pro؛ والمجاني بس في ردوده الـ 5 المجانية)

`change_song`

يغيّر بس اللي تطلبه («خلّ الطبول أثقل») ويحفظ نسخة جديدة.

الوسيط	النوع	وش هو
`song_id` (مطلوب)	string	معرّف اللحن (id)، من make_song أو write_song أو list_songs.
`request` (مطلوب)	string	وش تبغى تغيّر، بالكلام.
`wait_seconds`	number	كم ثانية ينتظر النتيجة قبل ما يكون الرد مهمة (job) (الافتراضي 40، والحد الأقصى 55).

API الويب: POST /v1/songs/:id/changes {request}

الباقة: رصيد الذكاء الاصطناعي

`get_song`

اسم اللحن، والكود، وأحدث نسخه، ورابط المشاركة.

الوسيط	النوع	وش هو
`song_id` (مطلوب)	string	معرّف اللحن (id)، من make_song أو write_song أو list_songs.

API الويب: GET /v1/songs/:id

الباقة: مجاني

`list_songs`

ألحانك، الأحدث أول، مع الـ id حق كل لحن.

بدون وسائط.

API الويب: GET /v1/songs

الباقة: مجاني

`restore_version`

يرجّع نسخة قديمة وتصير هي الأحدث. تنحفظ كنسخة جديدة، فما يضيع شي.

الوسيط	النوع	وش هو
`song_id` (مطلوب)	string	معرّف اللحن (id)، من make_song أو write_song أو list_songs.
`version_id` (مطلوب)	string	معرّف النسخة (id)، من get_song.

API الويب: GET /v1/songs/:id/versions, GET /v1/songs/:id/versions/:vid, POST /v1/songs/:id/versions/:vid/restore

الباقة: مجاني

`share_song`

رابط عام (shawarma.studio/s/…) يشتغل في أي متصفح بدون تسجيل دخول. لو شاركت مرة ثانية يتحدّث نفس الرابط.

الوسيط	النوع	وش هو
`song_id` (مطلوب)	string	معرّف اللحن (id)، من make_song أو write_song أو list_songs.
`nickname`	string	اسم صاحب اللحن في الصفحة. تحتاجه بس أول مرة تشارك.

API الويب: POST /v1/songs/:id/share {nickname?}

الباقة: مجاني

`export_audio`

يحوّل اللحن لملف MP3 أو WAV، لين 5 دقايق، ويرجّع رابط تنزيل لنفس المفتاح.

الوسيط	النوع	وش هو
`song_id` (مطلوب)	string	معرّف اللحن (id)، من make_song أو write_song أو list_songs.
`format`	"mp3" \| "wav"	mp3 (الافتراضي) أو wav.
`version_id`	string	النسخة اللي تبغى تحوّلها (الافتراضي: الأحدث).
`wait_seconds`	number	كم ثانية ينتظر النتيجة قبل ما يكون الرد مهمة (job) (الافتراضي 40، والحد الأقصى 55).

API الويب: POST /v1/songs/:id/exports {format?, version_id?}, GET /v1/jobs/:id/audio

الباقة: Pro

`list_sounds`

الأصوات اللي تقدر الألحان تستخدمها: آلات عربية مسجّلة (دربوكة، رق، عود، ناي) والمقامات، وطبول وأجهزة طبول، وسينثات، وآلات مسجّلة ثانية (بونقز، كونقا، أصوات بشرية وغيرها).

الوسيط	النوع	وش هو
`query`	string	جزء من اسم الصوت تدور عليه، مثلًا «guitar».

API الويب: GET /v1/sounds?query=

الباقة: مجاني

`write_song`

يحفظ كود موسيقى كتبه وكيلك، كلحن جديد أو كنسخة جديدة. Shawarma يفحصه أول، ويرفض الكود اللي ما يشتغل. بدون تكلفة ذكاء اصطناعي.

الوسيط	النوع	وش هو
`code` (مطلوب)	string	اللحن كامل بكود Shawarma للموسيقى (لين 100,000 حرف).
`title`	string	اسم اللحن الجديد.
`song_id`	string	احفظه كنسخة جديدة من هذا اللحن بدال لحن جديد.
`message`	string	وش تغيّر، لقائمة النسخ.

API الويب: POST /v1/songs {title, code}, PUT /v1/songs/:id/code {code}

الباقة: مجاني

`check_code`

يفحص كود الموسيقى بدون ما يحفظه: يشتغل ولا لا، والخطأ لو ما اشتغل، والأصوات اللي يستخدمها، وكم طوله.

الوسيط	النوع	وش هو
`code` (مطلوب)	string	كود Shawarma للموسيقى اللي تبغى تفحصه.

API الويب: POST /v1/check {code}

الباقة: مجاني

`guide`

دليل مختصر لكتابة كود Shawarma للموسيقى. اقرأه قبل write_song.

بدون وسائط.

API الويب: GET /v1/guide

الباقة: مجاني

`get_job`

حالة الطلب الطويل (make_song، change_song، export_audio): في الطابور، شغّال، خلص مع النتيجة، أو فشل مع السبب. يقدر ينتظره.

الوسيط	النوع	وش هو
`job_id` (مطلوب)	string	معرّف المهمة (job).
`wait_seconds`	number	كم ثانية ينتظر النتيجة قبل ما يكون الرد مهمة (job) (الافتراضي 40، والحد الأقصى 55).

API الويب: GET /v1/jobs/:id?wait=

الباقة: مجاني

مثال

سوّ لحن

curl https://shawarma.studio/v1/songs \
  -H "Authorization: Bearer shk_…" \
  -H "Content-Type: application/json" \
  -d '{"description": "calm 20-second intro for a podcast"}'

الرد (مختصر)

{
  "song": { "id": "calm-20-second-intro", "name": "Calm 20-second intro", "app_url": "https://shawarma.studio/open?song=…" },
  "version": { "n": 1 },
  "reply": "A soft piano intro with light drums, 20 seconds.",
  "job": { "id": "…", "status": "done" }
}

الشغل الطويل

التلحين والصوت ممكن ياخذون وقت. الطلب ينتظر النتيجة لين wait_seconds (الافتراضي 40، والحد الأقصى 55).
لو ما جهزت، الـ Web API يرد 202 مع { job }، وهيدر Location وRetry-After. وخادم MCP يرد بالمهمة ويقول لك تنادي get_job.
تحديث Shawarma ما يضيّع الشغل: المهمة تكمل على الخادم اللي بعده.
عندك رد ذكاء اصطناعي واحد بس شغّال في نفس الوقت، مشترك مع شات التطبيق. لو طلبت ثاني وواحد شغّال، يجيك 409 busy مع Retry-After.

المجاني وPro

الأداة	مجاني	Pro
make_song, change_song	بس في الردود الـ 5 المجانية، بعدها 402 pro_required	رصيد الذكاء الاصطناعي الشهري، والشحن الإضافي
write_song, restore_version	30 لحن جديد في اليوم (ضمن مشاريعك الـ 3)، و300 حفظ في اليوم	1000 لحن جديد و3000 حفظ في اليوم
check_code	300 في اليوم	3000 في اليوم
export_audio	402 pro_export	إيه، لين 5 دقايق صوت

شوف الأسعار

الحدود

لكل مفتاح أو اتصال: 300 طلب في 10 دقايق، و30 تلحين في الساعة.
الكود لين 100,000 حرف. وأقصى شي 20 مفتاح للشخص.
لو تعدّيت حد، الرد يكون 429 مع Retry-After.

اربط وكيلك

طريقة الإعداد لـ Claude Code وCodex وCursor وClaude.ai وChatGPT موجودة في صفحة المطوّرين.

شوف طريقة الإعداد