توليد الموسيقى

توليد الموسيقى غير متزامن. POST /v1/music/generations ينشئ مهمة TokenLab عامة ويعيد id / task_id، status، وعادةً poll_url. يجب على تطبيقك تخزين هوية تلك المهمة، عرض التقدم، والاستطلاع حتى الوصول إلى حالة نهائية.

اختر سير العمل

سير العمل	الحقول الرئيسية	ملاحظات
أغنية كاملة أو موسيقى تصويرية	`model`, `mv`, `prompt`, `title` اختياري، `tags`, `action: "MUSIC"`	استخدم عندما يتوقع المستخدم صوتًا نهائيًا
كلمات فقط	`model`, `prompt`, `action: "LYRICS"`	استخدم فقط مع النماذج التي تعرض توليد الكلمات
متابعة مقطع موجود	`continue_clip_id`, `continue_at` اختياري	قم بتخزين هوية المقطع/المهمة العامة السابقة قبل تقديم المتابعة

استعلم عن كتالوج النموذج الحالي قبل شحن قائمة نماذج مشفرة:

curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"

تستخدم الأمثلة العامة الحالية suno_music لتوليد الموسيقى وتتضمن mv مع إصدار نموذج Suno رسمي مثل chirp-v4. بالنسبة لتدفقات الكلمات فقط، أرسل action: "LYRICS" مع نموذج وثائقه العامة توثق توليد الكلمات واترك mv. اعتبر معرفات النماذج كمعرفات TokenLab العامة، وليس كضمان أن الحقول الخاصة بالمزود هي حقول تفاصيل النموذجة.

إنشاء مهمة موسيقية

curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "mv": "chirp-v4",
    "prompt": "مقطوعة موسيقية مبهجة من نوع الساينث بوب مع أصوات دافئة وكورس نظيف",
    "title": "صوت الصباح",
    "tags": "ساينث بوب، مبهج",
    "action": "MUSIC"
  }'

احتفظ بالمطالبات، العناوين، والوسوم مرئية للمستخدم وآمنة للتخزين. لا تضع مفاتيح API، روابط خاصة، أو معلومات تشخيص خاصة في أي حقل من حقول المطالبات.

الاستطلاع من أجل الاكتمال

استخدم poll_url أولاً. إذا كان عميلك يحتاج إلى مسار ثابت، اتصل بـ GET /v1/tasks/{id} مع id أو task_id المعاد.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

شكل الاستجابة

استجابة الإنشاء هي سجل مهمة يمكن استطلاعها، وليست ملف الصوت النهائي:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "suno_music"
}

يمكن أن تتضمن استجابة الاستطلاع المكتملة حقول الوسائط النهائية:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "completed",
  "audio_url": "https://cdn.example.com/music/abc123.mp3",
  "video_url": "https://cdn.example.com/music/abc123.mp4",
  "stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
  "image_url": "https://cdn.example.com/music/cover.jpg",
  "title": "Morning Static",
  "lyrics": "[Verse 1]\n..."
}

لا تظهر حقول الوسائط النهائية حتى يصبح status هو completed. تعيد المهام الفاشلة status: "failed" مع error. الحالات العامة المتوقعة هي pending، processing، completed، وfailed. يمكن أن تتضمن مهمة الموسيقى المكتملة audio_url، video_url، title، lyrics، وبيانات وصفية موحدة. قم بتخزين الروابط النهائية في قاعدة بياناتك الخاصة حتى يتمكن المستخدم من إعادة فتح النتيجة دون إعادة بدء التوليد.

واجهة المستخدم ومعالجة الحالة

عرض حالة الانتظار مباشرة بعد إنشاء المهمة.
الاستطلاع كل 5-10s للمهام الطويلة، ثم التوقف عند completed أو failed.
لا تعرض مشغلًا نهائيًا حتى تكون المهمة completed ويوجد audio_url.
بالنسبة لمهام الكلمات فقط، قم بعرض مخرجات النص بشكل منفصل عن مهام الصوت حتى يفهم المستخدمون ما يشترونه.
عند التحديث، استأنف من task_id المخزنة بدلاً من إنشاء مهمة جديدة.

الفوترة والتسوية

يمكن لمهام الموسيقى حجز مبلغ تقديري عند الإنشاء والتسوية بعد معرفة الحالة النهائية. قم بتخزين request_id، task_id، النموذج، نقطة النهاية، وbilling_transaction_id عند ظهوره. استخدم سجلات استخدام واجهة إدارة API للتسوية بدلاً من معرفات مهام المزود.

الأخطاء الشائعة

العرض	السبب المحتمل	الحل
تم إنشاء المهمة ولكن لا يوجد مشغل	المهمة لا تزال في حالة انتظار أو اكتملت بدون `audio_url`	استمر في الاستطلاع حتى الوصول إلى الحالة النهائية، ثم تعامل مع المخرجات المفقودة كوظيفة مستخدم فاشلة
أغاني مكررة بعد التحديث	أعادت واجهة المستخدم إنشاء المهمة بدلاً من الاستئناف	احتفظ وكرر استخدام `task_id`
مهمة الكلمات لا تعيد صوتًا	`action: "LYRICS"` هو نص فقط	فصل مسارات واجهة المستخدم للكلمات والموسيقى
معلمة غير مدعومة	الحقل غير موجود في تفاصيل النموذج العام	إزالة الحقول الخاصة بالمزود أو اختيار نموذج يوثقها

مرجع API

الموضوع	المرجع
إنشاء موسيقى	إنشاء موسيقى
الحصول على حالة الموسيقى	الحصول على حالة الموسيقى
الحصول على حالة المهمة	الحصول على حالة المهمة
قائمة النماذج	قائمة النماذج
الفوترة والتسعير	الفوترة والتسعير

البدء

الأدلة الأساسية

أدلة الوسائط

توليد الموسيقى

اختر سير العمل

إنشاء مهمة موسيقية

الاستطلاع من أجل الاكتمال

شكل الاستجابة

واجهة المستخدم ومعالجة الحالة

الفوترة والتسوية

الأخطاء الشائعة

مرجع API

​اختر سير العمل

​إنشاء مهمة موسيقية

​الاستطلاع من أجل الاكتمال

​شكل الاستجابة

​واجهة المستخدم ومعالجة الحالة

​الفوترة والتسوية

​الأخطاء الشائعة

​مرجع API

اختر سير العمل

إنشاء مهمة موسيقية

الاستطلاع من أجل الاكتمال

شكل الاستجابة

واجهة المستخدم ومعالجة الحالة

الفوترة والتسوية

الأخطاء الشائعة

مرجع API