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

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

اختر سير العملCopy Anchor Link

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

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 العامة، وليس كضمان أن الحقول الخاصة بالمزود هي حقول تفاصيل النموذجة.

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

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، روابط خاصة، أو معلومات تشخيص خاصة في أي حقل من حقول المطالبات.

الاستطلاع من أجل الاكتمالCopy Anchor Link

استخدم 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"

شكل الاستجابةCopy Anchor Link

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

{
  "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، وبيانات وصفية موحدة. قم بتخزين الروابط النهائية في قاعدة بياناتك الخاصة حتى يتمكن المستخدم من إعادة فتح النتيجة دون إعادة بدء التوليد.

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

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

الفوترة والتسويةCopy Anchor Link

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

الأخطاء الشائعةCopy Anchor Link

مرجع APICopy Anchor Link