# مرجع Shawarma API

> كل أدوات خادم MCP وواجهة الويب في Shawarma: المعطيات، المسارات، المفاتيح والصلاحيات، المهام الطويلة، وحدود المجاني وPro، مع مثال.

Shawarma يسوّي موسيقى آلية (بدون غناء) من كلامك، ويغيّر بس الجزء اللي تطلبه. كل لحن مكتوب كود، فأي تغيير هو تعديل، وكل نسخة محفوظة. وكيلك (agent) يستخدمه عن طريق خادم MCP، وكودك أنت عن طريق الـ Web API. الاثنين فيهم نفس الأدوات.

[خذ مفتاح API](https://shawarma.studio/auth/google?return=%2Far) [جهّز وكيلك](https://shawarma.studio/ar/developers#setup)

## العناوين

| المدخل | العنوان | لمين |
| --- | --- | --- |
| خادم 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 دقايق صوت |

[شوف الأسعار](https://shawarma.studio/ar/pricing)

## الحدود

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

## اربط وكيلك

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

[شوف طريقة الإعداد](https://shawarma.studio/ar/developers#setup)

---

الصفحة: https://shawarma.studio/ar/docs/api