أدلة الوسائط

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

أنشئ أغانٍ أو كلمات أغانٍ وانتظر حتى اكتمال الصوت

توليد الموسيقى هو عملية غير متزامنة (asynchronous). يقوم POST /v1/music/generations بإرجاع معرف المهمة (task ID)، والحالة، وعادةً poll_url. قم بعمل GET /v1/tasks/{id} باستخدام ذلك المعرف حتى تصبح حالة المهمة completed أو failed.

اختر ما تريد إنشاءه

ما تريد إنشاءهالحقول الرئيسيةملاحظات
أغنية كاملة أو مقطوعة موسيقيةmodel, mv, prompt, اختياري title, tags, action: "MUSIC"استخدمه عندما يتوقع المستخدم الحصول على الصوت النهائي
كلمات الأغاني فقطmodel, prompt, action: "LYRICS"استخدمه فقط مع النماذج التي تدعم توليد كلمات الأغاني
متابعة مقطع موجودmodel, mv, prompt, continue_clip_id, اختياري continue_atاحتفظ بمعرف المقطع السابق
غناء (Cover) أو تمديد صوتك الخاصmodel, mv, prompt, audio_url, اختياري audio_operationيجب أن يكون audio_url رابطاً عاماً. audio_operation هو upload-cover افتراضياً؛ يتطلب upload-extend أيضاً continue_at
إضافة آلات موسيقية، استبدال مقطع، أو فصل المساراتaudio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation, أو advanced-splitكل عملية لها حقولها المطلوبة؛ راجع إنشاء الموسيقى

احصل على قائمة نماذج الموسيقى الحالية من:

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

يستخدم المثال أدناه suno-music مع mv: "chirp-v6". تستخدم نماذج الموسيقى الأخرى، مثل stable-audio-3، حقولاً مختلفة مثل duration و output_format؛ اقرأ تفاصيل النموذج أولاً. بالنسبة لكلمات الأغاني فقط، اختر نموذجاً يوثق توليد الكلمات، وأرسل action: "LYRICS"، واحذف mv.

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

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-v6",
    "prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
    "title": "Morning Static",
    "tags": "synth-pop, upbeat",
    "action": "MUSIC"
  }'

قد تظهر المطالبات (prompts)، والعناوين، والوسوم في سجل منتجك. لا تضع أبداً مفاتيح API، أو روابط خاصة، أو بيانات تشخيصية فيها.

الحصول على الصوت النهائي

قم باستدعاء 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://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
  "video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
  "image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
  "title": "Morning Static",
  "lyrics": "[Verse 1]\n...",
  "media_retention": {
    "days": 30,
    "items": [
      {
        "url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
        "kind": "audio",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      },
      {
        "url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
        "kind": "video",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      },
      {
        "url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
        "kind": "image",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      }
    ]
  }
}

تكون حقول الوسائط النهائية غائبة حتى تصبح الحالة completed. المهام الفاشلة تعيد status: "failed" مع error.

الحالات هي pending، و processing، و completed، و failed. يمكن أن تتضمن المهمة المكتملة audio_url، و video_url، و title، و lyrics، وبيانات وصفية أخرى. روابط الوسائط هي روابط TokenLab تظل صالحة لمدة 30 يوماً؛ قم بتنزيل أو حفظ أي نتيجة تحتاجها لفترة أطول.

عرض الحالة الصحيحة

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

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

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

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

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

مرجع API

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

في هذه الصفحة