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

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

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

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال رابط الصوت voice_url، للحصول على النتيجة المعالجة، المحتوى المحدد كما يلي:

يمكنك أن ترى أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء واجهة برمجة التطبيقات، بعد التقديم يمكنك اختياره مباشرة من القائمة المنسدلة.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • voice_url: رابط الصوت الذي تم تحميله.
  • title: معلومات عنوان هذه النغمة.
  • image_urls: صورة الغلاف لهذه النغمة.
  • description: معلومات وصف هذه النغمة.
  • callback_url: URL الذي يحتاج إلى استرجاع النتائج.
بعد الاختيار، يمكنك أن تلاحظ أنه تم إنشاء كود مطابق على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء اختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "task_id": "b01db503-dd9e-4f92-861a-344f14756217",
  "trace_id": "8731a2f1-7736-4a47-98e7-da942f9346a7",
  "data": {
    "_id": "d5d21261512b4852b9ccd709facf93f3",
    "type": "tts",
    "title": "test",
    "description": "test",
    "cover_image": "coverimage/d5d21261512b4852b9ccd709facf93f3",
    "train_mode": "fast",
    "state": "trained",
    "tags": [],
    "samples": [
      {
        "title": "Default Sample",
        "text": "من خلال المراقبة الطويلة، تم اكتشاف أن الأسماك في نظام الشعاب المرجانية لديها أنماط سلوكية جماعية معقدة. تستخدم هذه الأسماك تغيرات الألوان ووضعيات السباحة المحددة لنقل المعلومات، وهذا النظام الدقيق من التواصل غير اللفظي يظهر حكمة تكيف الكائنات البحرية.",
        "task_id": "4ae961828fc94c07b2103dc039a8466b",
        "audio": "task/4ae961828fc94c07b2103dc039a8466b.mp3"
      }
    ],
    "created_at": "2025-09-21T07:29:41.058506Z",
    "updated_at": "2025-09-21T07:29:41.057917Z",
    "languages": [
      "zh"
    ],
    "visibility": "public",
    "lock_visibility": false,
    "default_text": "من خلال المراقبة الطويلة، تم اكتشاف أن الأسماك في نظام الشعاب المرجانية لديها أنماط سلوكية جماعية معقدة. تستخدم هذه الأسماك تغيرات الألوان ووضعيات السباحة المحددة لنقل المعلومات، وهذا النظام الدقيق من التواصل غير اللفظي يظهر حكمة تكيف الكائنات البحرية.",
    "like_count": 0,
    "mark_count": 0,
    "shared_count": 0,
    "task_count": 0,
    "unliked": false,
    "liked": false,
    "marked": false,
    "author": {
      "_id": "7ecad23df62a4174acd6a2a6cb5201ee",
      "nickname": "Matthew Garcia",
      "avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
    }
  }
}
تتضمن النتيجة العائدة عدة حقول، كما هو موضح أدناه:
  • success: حالة مهمة إنشاء النغمة في ذلك الوقت.
    • data: نتيجة مهمة الموسيقى
      • _id: معرف مهمة إنشاء النغمة في ذلك الوقت، والذي سيتم استخدامه لاحقًا في إنشاء أصوات مكررة.
      • title: عنوان النغمة.
      • image_url: معلومات غلاف النغمة.
      • description: معلومات وصف النغمة.
      • train_mode: الوضع المستخدم في مهمة إنشاء النغمة في ذلك الوقت.
      • tags: أسلوب النغمة.
      • default_text: معلومات نص الصوت لمهمة إنشاء النغمة في ذلك الوقت.
يمكنك أن ترى أننا حصلنا على معلومات نغمة مرضية، كل ما علينا فعله هو استخدام _id من data لإجراء مهمة تكرار الصوت. بالإضافة إلى ذلك، إذا كنت ترغب في إنشاء كود الدمج المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/fish/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "voice_url": "https://platform.r2.fish.audio/task/604133d7b3c7430385382470f67770e8.mp3",
  "title": "test",
  "description": "test"
}'

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

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

عند النقر على التشغيل، يمكنك أن تلاحظ أنك ستحصل على نتيجة على الفور، كما يلي: 
{
  "task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8"
}
稍等片刻，我们可以在 https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34 上观察到生成任务的结果，如图所示： 内容如下： 
{
    "success": true,
    "task_id": "9f626a13-96ec-4dec-8846-dc5aab7362a8",
    "trace_id": "3fcdea82-7c1c-4a0a-b8d8-f7616f722d8f",
    "data": {
        "_id": "fa75e7c3f02f42e79a6aa622b6cf075e",
        "type": "tts",
        "title": "test",
        "description": "test",
        "cover_image": "coverimage/fa75e7c3f02f42e79a6aa622b6cf075e",
        "train_mode": "fast",
        "state": "trained",
        "tags": [],
        "samples": [
            {
                "title": "Default Sample",
                "text": "الدلافين تتنقل في المحيط من خلال نظام تحديد المواقع بالصدى، هذه التقنية الصوتية الدقيقة تمكنها من استكشاف البيئة المحيطة، والبحث عن الطعام وتجنب المخاطر. هذا لا يظهر فقط قدرة الكائنات البحرية على التكيف، بل يكشف أيضًا عن التصميم الرائع للطبيعة.",
                "task_id": "68cdda24d26e4794bae177e20da740db",
                "audio": "task/68cdda24d26e4794bae177e20da740db.mp3"
            }
        ],
        "created_at": "2025-09-21T07:36:20.200865Z",
        "updated_at": "2025-09-21T07:36:20.200353Z",
        "languages": [
            "zh"
        ],
        "visibility": "public",
        "lock_visibility": false,
        "default_text": "الدلافين تتنقل في المحيط من خلال نظام تحديد المواقع بالصدى، هذه التقنية الصوتية الدقيقة تمكنها من استكشاف البيئة المحيطة، والبحث عن الطعام وتجنب المخاطر. هذا لا يظهر فقط قدرة الكائنات البحرية على التكيف، بل يكشف أيضًا عن التصميم الرائع للطبيعة.",
        "like_count": 0,
        "mark_count": 0,
        "shared_count": 0,
        "task_count": 0,
        "unliked": false,
        "liked": false,
        "marked": false,
        "author": {
            "_id": "7ecad23df62a4174acd6a2a6cb5201ee",
            "nickname": "Matthew Garcia",
            "avatar": "avatars/7ecad23df62a4174acd6a2a6cb5201ee.jpg"
        }
    }
}
可以看到结果中有一个 task_id 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。

​
错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
  • 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"
}

​
结论

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