الانتقال إلى المحتوى الرئيسي
ستتناول هذه المقالة تعليمات دمج واجهة برمجة تطبيقات توليد أصوات السمك، والتي يمكن من خلالها استنساخ صوتك الخاص عن طريق إدخال كلمات دلالية.

​
عملية التقديم

لاستخدام واجهة برمجة التطبيقات، يجب أولاً زيارة صفحة واجهة برمجة تطبيقات توليد أصوات السمك للتقدم للحصول على الخدمة المناسبة، بعد دخول الصفحة، انقر على زر “Acquire”، كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، بعد تسجيل الدخول أو التسجيل، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

​
الاستخدام الأساسي

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة دلالية prompt، وسلوك الاستنساخ action، ومعرف الصوت voice_id، والنموذج model، للحصول على النتيجة المعالجة. أولاً، تحتاج إلى تمرير حقل action، وقيمته هي generate، ثم نحتاج أيضًا إلى إدخال النموذج model، والذي يتضمن حاليًا نموذج fish-tts، المحتوى المحدد كما يلي:

يمكنك أن ترى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء واجهة برمجة التطبيقات، بعد التقديم يمكنك اختياره مباشرة من القائمة المنسدلة.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • model: نموذج استنساخ الصوت، والذي يتضمن بشكل رئيسي نموذج fish-tts.
  • action: سلوك مهمة استنساخ الصوت هذه.
  • prompt: الكلمة الدلالية التي تحتاج إلى استنساخها.
  • voice_id: استنساخ بناءً على معرف الصوت.
  • callback_url: عنوان URL الذي تحتاج إلى استدعاء النتيجة إليه.
بعد الاختيار، يمكنك أن تلاحظ أن الكود المقابل قد تم إنشاؤه على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "task_id": "5872ab00-3cf4-4040-a798-8510aaa16756",
  "trace_id": "5eda3694-448a-4b72-af33-2acb3851ffe1",
  "data": [
    {
      "audio_url": "https://platform.r2.fish.audio/task/8a72ff9840234006a9f74cb2fa04f978.mp3"
    }
  ]
}
تتضمن النتيجة عدة حقول، كما هو موضح أدناه:
  • success: حالة مهمة استنساخ الصوت في ذلك الوقت.
    • data: نتيجة مهمة استنساخ الصوت
      • audio_url: رابط الصوت الناتج عن مهمة استنساخ الصوت في ذلك الوقت.
يمكنك أن ترى أننا حصلنا على معلومات صوتية مرضية، كل ما علينا هو الحصول على الصوت المستنسخ بناءً على عنوان الرابط الموسيقي في data. بالإضافة إلى ذلك، إذا كنت ترغب في توليد الكود المقابل للدمج، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/fish/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "speech",
  "prompt": "a white siamese cat",
  "model": "fish-tts",
  "voice_id": "d7900c21663f485ab63ebdb7e5905036"
}'

​
الاستدعاء غير المتزامن

نظرًا لأن الوقت المستغرق لتوليد واجهة برمجة تطبيقات توليد أصوات السمك نسبيًا طويل، حوالي 1-2 دقيقة، إذا لم يكن هناك استجابة من واجهة برمجة التطبيقات لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا توفر هذه الواجهة أيضًا دعم الاستدعاء غير المتزامن. تتمثل العملية العامة في: عندما يقوم العميل بإرسال الطلب، يحدد حقل callback_url إضافي، بعد أن يقوم العميل بإرسال طلب واجهة برمجة التطبيقات، ستقوم الواجهة بإرجاع نتيجة على الفور، تتضمن معلومات حقل task_id، الذي يمثل معرف المهمة الحالية. عند الانتهاء من المهمة، سيتم إرسال نتيجة المهمة المولدة إلى callback_url المحدد من قبل العميل عبر POST JSON، والتي تتضمن أيضًا حقل task_id، بحيث يمكن ربط نتيجة المهمة من خلال المعرف. دعونا نفهم كيفية القيام بذلك من خلال مثال. أولاً، يعد استدعاء Webhook خدمة يمكنها استقبال طلبات HTTP، يجب على المطور استبدالها بعنوان URL الخاص بخادم HTTP الذي قام بإنشائه. هنا، لتسهيل العرض، نستخدم موقع Webhook عينة عام https://webhook.site/، افتح هذا الموقع للحصول على عنوان Webhook URL، كما هو موضح في الصورة: انسخ هذا URL، يمكنك استخدامه كـ Webhook، وعنوان العينة هنا هو https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34. بعد ذلك، يمكننا تعيين حقل callback_url إلى عنوان Webhook المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الصورة:

انقر على تشغيل، يمكنك أن تلاحظ أنك ستحصل على نتيجة على الفور، كما يلي: 
{
  "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5"
}
بعد قليل، يمكنك ملاحظة نتيجة المهمة المولدة على https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34، كما هو موضح في الصورة: المحتوى كما يلي: 
{
    "success": true,
    "task_id": "2725a2d3-f87e-4905-9c53-9988d5a7b2f5",
    "trace_id": "e2d308bc-4df8-4c69-9369-a60f3c54f2b3",
    "data": [
        {
            "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
        }
    ]
}
يمكنك أن ترى أن النتيجة تحتوي على حقل task_id، بينما الحقول الأخرى مشابهة لما سبق، من خلال هذا الحقل يمكنك تحقيق الربط بين المهام.

​
معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم الواجهة بإرجاع رمز الخطأ والمعلومات المناسبة. على سبيل المثال:
  • 400 token_mismatched: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented: طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token: غير مصرح به، رمز تفويض غير صالح أو مفقود.
  • 429 too_many_requests: عدد كبير جدًا من الطلبات، لقد تجاوزت الحد الأقصى لمعدل الطلبات.
  • 500 api_error: خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

​
مثال على استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
الخاتمة

من خلال هذه الوثيقة، لقد تعرفت على كيفية استخدام واجهة برمجة تطبيقات توليد الصوت من Fish من خلال إدخال كلمات مفتاحية لاستنساخ الصوت. نأمل أن تساعدك هذه الوثيقة في التوصيل واستخدام هذه الواجهة بشكل أفضل. إذا كان لديك أي أسئلة، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.