ثبّت إضافتي FishAudio TTS 文字转语音 وMedia Sync في Coze واستخدم API Key الخاص بك لإنشاء الصوت والفيديو المتزامن.

استخدام FishAudio في Coze

يوفر FishAudio إضافتين في متجر Coze. تثبيت الإضافتين هو المسار الموصى به؛ استخدم إعداد HTTP المباشر فقط للطلبات المخصصة.

الإضافة	الاستخدام	التثبيت
FishAudio TTS 文字转语音	تحويل النص إلى كلام وإرجاع رابط صوت	فتح في Coze
FishAudio 图片/视频对口型	إنشاء مهمة مزامنة غير متزامنة من روابط الفيديو والصوت	فتح في Coze

إعداد API Key

أنشئ مفتاحًا مخصصًا لـ Coze من صفحة إدارة API، وتحقق من رصيد API. مرّر المفتاح بهذا الشكل:

Authorization: Bearer YOUR_FISH_AUDIO_API_KEY

يجب وجود مسافة واحدة بعد Bearer. يستخدم كل عميل مفتاحه الخاص، وتُحسب التكلفة على حساب Fish Audio الخاص به.

إذا لم ترغب في استخدام إضافات المتجر، نزّل FishAudio TTS 文字转语音 OpenAPI أو FishAudio 图片/视频对口型 OpenAPI أو FishAudio 文字对口型 OpenAPI أو FishAudio 专属语音合成 OpenAPI واستورده في Coze كإضافة سحابية مبنية على خدمة موجودة. اختر عدم استخدام تفويض ثابت، ومرّر Authorization الخاص بالعميل وقت التشغيل. راجع الدليل الإنجليزي.

يُنصح باستخدام زر Import في أعلى اليمين؛ فهذا المسار يحتاج إلى ملف OpenAPI YAML فقط. إذا ظهرت خانة ai_plugin (JSON) يسارًا وopenapi (YAML) يمينًا، فأنت في صفحة الإنشاء البرمجي </>. لا تترك ai_plugin فارغًا: الصق ملف *.ai-plugin.json المطابق يسارًا وملف *.openapi.yaml الذي يحمل البادئة نفسها يمينًا. ملف manifest.json هو قائمة محتويات حزمة FishAudio فقط، وليس ملف ai_plugin.

الحالة الحالية: يتوفر FishAudio TTS 文字转语音 وFishAudio 图片/视频对口型 في المتجر، بينما يتوفر FishAudio 文字对口型 وFishAudio 专属语音合成 للاستيراد كإضافات خاصة فقط.

استخدام FishAudio TTS 文字转语音

أضف FishAudio TTS 文字转语音 إلى مساحة Coze الخاصة بك.
أضف أداة TTS إلى الوكيل أو سير العمل.
أدخل Authorization والنص وVoice ID والإعدادات الاختيارية.
صِل audio_url الناتج بالتشغيل أو التنزيل أو Media Sync.

ابدأ بجملة قصيرة. يجب أن يكون Voice ID لصوت نظام صالح أو صوت مخصص متاح للحساب الحالي.

استخدام FishAudio 图片/视频对口型

تتضمن FishAudio 图片/视频对口型 أداتين:

الأداة	الاستخدام
`create_media_sync`	إنشاء مهمة من روابط فيديو وصوت قابلة للتنزيل المباشر
`get_media_sync_job`	الاستعلام عن التقدم أو النتيجة أو الخطأ باستخدام `jobId`

مرّر Authorization وvideo_url وaudio_url إلى create_media_sync. احفظ data.id واستخدمه بوصفه jobId. إنشاء المهمة يستهلك رصيد API.

processing: انتظر ثم استعلم عن jobId نفسه.
completed: اقرأ data.result_url.
failed: اقرأ data.error_message.

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

سير عمل من النص إلى فيديو متزامن

يمكنك ربط إضافتي المتجر كما يلي، أو استيراد FishAudio 文字对口型 الخاص لتنفيذ TTS ومزامنة الشفاه في عملية إنشاء واحدة:

Text + Voice ID → FishAudio TTS 文字转语音 → audio_url
video_url + audio_url → create_media_sync → data.id
احفظ jobId → انتظر 15–30 ثانية → get_media_sync_job
completed: data.result_url | failed: data.error_message

عند استخدام الاستعلام التلقائي، عيّن حدًا أقصى لعدد المحاولات ومهلة إجمالية.

تستخدم الإضافة الخاصة create_text_lip_sync ثم get_text_lip_sync_job. استخدم Idempotency-Key جديدًا لكل مهمة جديدة، وأعد استخدامه فقط عند إعادة محاولة الطلب نفسه تمامًا.

روابط الوسائط وأمان المفتاح

يجب أن يتمكن Fish Audio من تنزيل روابط الفيديو والصوت مباشرة. لا تصلح صفحات الويب أو المسارات المحلية أو الروابط الموقعة المنتهية. يجب أن يبقى رابط Coze المؤقت صالحًا حتى يكتمل التنزيل.

قد يظهر Authorization في محادثات Coze أو سجلات التصحيح والتشغيل. أنشئ مفتاحًا مخصصًا لـ Coze، ولا تشارك صورًا أو قوالب تحتوي على مفتاح حقيقي، وبدّل مفاتيح الاختبار أو ألغها. لا تضع مفتاحًا مشتركًا داخل إضافة عامة.

استكشاف الأخطاء

401: تحقق من Bearer والمسافات الزائدة وصلاحية المفتاح.
402: تحقق من رصيد API؛ فهو منفصل عن رصيد الاشتراك.
فشل تنزيل الوسائط: تحقق من الوصول المباشر ومدة صلاحية الرابط.
استمرار processing: استعلم عن jobId نفسه ولا تنشئ مهمة جديدة.
ظهور المفتاح في السجل: ألغِه وأنشئ مفتاح Coze جديدًا.

متقدم: استدعاء TTS HTTP API مباشرة

يمكن لعقدة HTTP في Coze استدعاء POST https://fishaudio.org/v1/audio/speech مع Authorization وContent-Type: application/json. أرسل model وvoice وinput وresponse_format: "mp3"، واضبط الاستجابة كملف أو بيانات ثنائية بدل JSON.

إعداد Coze