دليل تكامل Fish TTS API

توفر هذه الواجهة تحويل النص إلى كلام، واستدعاء الأصوات المحفوظة، واستنساخ الصوت الفوري لمرة واحدة، وعنوانها هو POST https://api.acedata.cloud/fish/tts。

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

لاستخدام Fish TTS API، انتقل أولاً إلى لوحة تحكم Ace Data Cloud للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا.

إذا لم تكن قد سجلت الدخول أو أنشأت حسابًا بعد، فسيتم توجيهك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك إلى التسجيل وتسجيل الدخول، وستعود تلقائيًا إلى الصفحة الحالية بعد الإكمال. يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة. سيُمنح طلبك الأول رصيدًا مجانيًا للتجربة مجانًا؛ وعند عدم كفاية الرصيد، يمكنك شحن الرصيد العام من لوحة التحكم.

📘 الوثائق الكاملة: Fish TTS API →

رؤوس الطلب

Header	مطلوب	الوصف
`authorization`	نعم	`Bearer {token}`، حيث إن `{token}` هو المفتاح الذي تم التقديم عليه في هذه المنصة.
`content-type`	نعم	`application/json`。
`accept`	لا	`application/json`。
`model`	لا	نموذج TTS، يمكن اختيار `s1` أو `s2-pro` أو `s2.1-pro`، والافتراضي هو `s2-pro`。`s2.1-pro` هو أحدث جيل، و `s2-pro` يتمتع بتعبيرية قوية؛ أما `s1` فهو أكثر استقرارًا وأقل عرضة للانحراف مع النصوص الطويلة. الثلاثة بالسعر نفسه.

حقول جسم الطلب

الحقل	النوع	مطلوب	الوصف
`text`	string	نعم	النص المطلوب تركيبه، سلسلة نصية غير فارغة.
`format`	string	لا	تنسيق الصوت الناتج، يمكن اختيار `mp3` (الافتراضي) أو `wav` أو `pcm`。كلا `wav` و`pcm` يعيدان حاوية WAV. لا يتم دعم `opus`، وسيؤدي تمريره إلى إرجاع `400` مباشرةً.
`reference_id`	string \| string[]	لا	معرّف نموذج لصوت محفوظ أو عام، ويمكن إنشاؤه عبر Fish Model API، أو البحث عنه في Fish Model Query。لا يمكن استخدامه مع `references` في الوقت نفسه.
`references`	object[]	لا	استنساخ صوت فوري لمرة واحدة، يدعم عينة واحدة فقط بصيغة `{audio, text}`: يكون `audio` رابط MP3/WAV عام عبر HTTPS، و`text` هو النص الحرفي الدقيق للصوت. لا يمكن استخدامه مع `reference_id` في الوقت نفسه.
`sample_rate`	integer	لا	معدل العينة، الشائع هو `16000` و`22050` و`44100`。الافتراضي لـ `format=mp3` هو 44100.
`mp3_bitrate`	integer	لا	معدل بت MP3، يمكن اختيار `64` أو `128` أو `192`。يكون فعالاً فقط عند `format=mp3`。
`prosody`	object	لا	تجاوز الإيقاع، يدعم `speed` (سرعة الكلام، 1.0 هي السرعة الأصلية) و`volume` (كسب الصوت بوحدة dB). على سبيل المثال `{"speed":1.2,"volume":0}`。
`chunk_length`	integer	لا	طول التقسيم في المصدر، ويُحدد المصدر الافتراضي ذلك.
`temperature`	number	لا	درجة حرارة أخذ العينات، النطاق حوالي 0.0–1.0。
`top_p`	number	لا	معلمة أخذ عينات top-p。
`latency`	string	لا	`normal` أو `balanced`، وعند عدم التحديد ستضيف هذه الواجهة تلقائيًا `normal` (تمرير سلسلة فارغة مباشرةً سيرفضه المصدر).
`normalize`	boolean	لا	ما إذا كان يجب إجراء تطبيع للنص.
`callback_url`	string	لا	عنوان رد الاتصال غير المتزامن، انظر «رد الاتصال غير المتزامن» أدناه للتفاصيل. هذا امتداد مقارنةً بالواجهة الرسمية。

لا يقبل الاستنساخ لمرة واحدة سوى روابط الصوت عبر HTTPS، ولا يقبل MessagePack أو Base64 أو data URI أو الروابط التي تحتوي على بيانات اعتماد. يُنصح بأن يكون طول الصوت المرجعي من 10 إلى 270 ثانية؛ ويستخدم Studio نطاقًا أكثر تحفظًا من 10 إلى 60 ثانية.

المثال 1: الحد الأدنى للطلب (`text` + `format=mp3`)

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hello world.",
    "format": "mp3"
  }'

الإرجاع (تم اختباره):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d-230825dfc559.mp3"
}

يشير audio_url إلى CDN الخاص بهذه المنصة، ويمكن تنزيله مباشرةً باستخدام GET أو تشغيله ضمن <audio>。سيعيد رد النجاح النهائي أيضًا cost في المستوى الأعلى، حيث إن amount هو عدد Credits المخصومة فعليًا هذه المرة؛ وإذا كان هناك خصم على الحساب، فإن list_amount يمثل الرصيد قبل الخصم. الرابط متاح على المدى الطويل، لكن لا يزال يُنصح بالاحتفاظ بنسخة في التخزين الخاص بك.

المثال 2: استخدام نبرة صوت مستنسخة `reference_id`

فيما يلي استخدام نبرة صوت إسبانية عامة على منصة Fish (يمكن الحصول على _id عبر البحث في Fish Model Query):

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Hermanos míos, hoy es un buen día.",
    "reference_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
    "format": "mp3"
  }'

الإرجاع (تم اختباره):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/b6f161f2-a100-4818-add2-47694f234659-6532864739de.mp3"
}

المثال 3: استنساخ صوت فوري لمرة واحدة (`references`)

ضع الصوت المرجعي على عنوان HTTPS عام، وقدّم النص الأصلي الدقيق الذي قيل فيه فعليًا. يُستخدم هذا الصوت لهذه العملية فقط، ولن يتم إنشاء نموذج طويل الأمد:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s2-pro' \
  -d '{
    "text": "新的旅程从这一刻开始，让我们一起向前。",
    "format": "mp3",
    "references": [{
      "audio": "https://cdn.acedata.cloud/assets/examples/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9-570cfdf96ad9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

استجابة نجاح تم اختبارها فعليًا:

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/995dfe37-b187-474d-8323-b08d6678ed8f-6359be9f8873.mp3",
  "cost": {"amount": 0.007609319999999999, "currency": "credit"}
}

الطريقة	دورة الحياة	سيناريوهات الاستخدام
`references`	لطلب TTS هذا فقط	استخدام مؤقت أو صوت مختلف في كل مرة
`reference_id`	قابل لإعادة الاستخدام	صوت عام أو صوت طويل الأمد تم إنشاؤه عبر `/fish/model`

المثال 3: ضبط سرعة الكلام / مستوى الصوت (`prosody`)

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "Faster speech with prosody overrides.",
    "prosody": { "speed": 1.2, "volume": 0 },
    "format": "mp3"
  }'

الإرجاع (تم اختباره فعليًا):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"
}

تزيد speed عن 1 السرعة، وتقللها إذا كانت أقل من 1؛ ووحدة volume هي dB، حيث يشير 0 إلى عدم التغيير، والقيمة الموجبة إلى زيادة، والقيمة السالبة إلى خفض.

المثال 5: تبديل النموذج + التحكم في معدل البت

قم بالتبديل إلى نموذج الاستقرار عبر ترويسة HTTP model: s1، وأضف mp3_bitrate: 128 في نص الطلب للتحكم في معدل بت MP3:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -H 'model: s1' \
  -d '{
    "text": "high bitrate mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

الإرجاع (تم اختباره فعليًا):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e-6f11bf2f30e9.mp3"
}

المثال 6: شكل موجة PCM الخام

بالنسبة للسيناريوهات التي تتطلب إجراء تجميع فوري في المتصفح، أو معالجة لاحقة على العميل (المزج، تغيير السرعة)، يوصى باستخدام pcm:

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "hi",
    "format": "pcm",
    "sample_rate": 16000
  }'

الإرجاع (تم اختباره فعليًا):

{
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/64adc04b-c196-4a0f-9070-222ba101ce6c-fc50de38c165.wav"
}

امتداد الرابط يتبع format في الطلب: يؤدي mp3 إلى .mp3، ويؤدي wav وpcm إلى .wav (حاوية WAV، PCM بعمق 16 بت).

رد الاتصال غير المتزامن (`callback_url`)

قد يستغرق تركيب النصوص الطويلة دفعة واحدة من عشرات الثواني، وإذا انقطع الاتصال يلزم إعادة المحاولة. بعد تمرير callback_url في نص الطلب، ستعيد الواجهة فورًا {task_id, started_at}، وعند إكمال المصدر الفعلي ستُرسل النتيجة الكاملة كـ POST JSON إلى عنوان URL هذا، مع تضمين نفس task_id وcost ذي المستوى الأعلى للفوترة النهائية لهذه المرة في نص الطلب. تأكيد المهمة الأولي لم يُكمل التركيب بعد، لذلك لا يتضمن cost.

curl -X POST 'https://api.acedata.cloud/fish/tts' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "text": "今天天气真好，我们一起出去散散步吧。",
    "format": "mp3",
    "callback_url": "https://webhook.site/4815f79f-a40f-4078-ac85-1cc126b6bb34"
  }'

الإرجاع الفوري (تم اختباره فعليًا):

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": 1778462584.742
}

لاحقًا، سيتلقى callback_url ما يشبه:

{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/bd66b8c5-7543-4557-b684-baa72407e336-52f2e79732f2.mp3"
}

يمكنك أيضًا استخدام Fish Tasks API لسحب النتيجة بشكل نشط حسب task_id؛ تتطابق response.cost في سجل الحالة النهائية مع cost في رد الاتصال، راجع تلك الوثائق للتفاصيل.

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

400 token_mismatched: معلمات الطلب مفقودة أو غير صالحة (الأكثر شيوعًا أن يكون text فارغًا، أو أن يتم تمرير قيمة غير mp3/wav/pcm إلى format).
401 invalid_token: رمز المصادقة token غير موجود أو غير صالح.
429 too_many_requests: تم تفعيل حد معدل الحساب.
500 api_error: خطأ داخلي في الخادم.

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

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

ستوضح أخطاء التحقق من المعلمات الحقل غير الصالح في حقل message، على سبيل المثال:

{
  "status": 400,
  "message": "[{\"type\":\"literal_error\",\"loc\":[\"format\"],\"msg\":\"Input should be 'pcm' or 'mp3'\",\"input\":\"wav\"}]"
}

الخلاصة

أقل تكلفة لدمج Fish TTS هي: استبدال المصادقة برمز token الخاص بهذه المنصة في الكود الحالي الذي يستدعي api.fish.audio/v1/tts، وإضافة format: "mp3" بشكل صريح في نص الطلب. يوصى باستخدام رد الاتصال غير المتزامن callback_url لسيناريوهات النصوص الطويلة؛ ولاكتشاف reference_id للأصوات المستنسخة، يرجى استخدام Fish Model Query مع Fish Model Get.

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

Coding

المزيد من الأدلة

دليل تكامل Fish TTS API

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

رؤوس الطلب

حقول جسم الطلب

المثال 1: الحد الأدنى للطلب (`text` + `format=mp3`)

المثال 2: استخدام نبرة صوت مستنسخة `reference_id`

المثال 3: استنساخ صوت فوري لمرة واحدة (`references`)

المثال 3: ضبط سرعة الكلام / مستوى الصوت (`prosody`)

المثال 5: تبديل النموذج + التحكم في معدل البت

المثال 6: شكل موجة PCM الخام

رد الاتصال غير المتزامن (`callback_url`)

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

الخلاصة

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

​رؤوس الطلب

​حقول جسم الطلب

​المثال 1: الحد الأدنى للطلب (text + format=mp3)

​المثال 2: استخدام نبرة صوت مستنسخة reference_id

​المثال 3: استنساخ صوت فوري لمرة واحدة (references)

​المثال 3: ضبط سرعة الكلام / مستوى الصوت (prosody)

​المثال 5: تبديل النموذج + التحكم في معدل البت

​المثال 6: شكل موجة PCM الخام

​رد الاتصال غير المتزامن (callback_url)

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

​الخلاصة

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

رؤوس الطلب

حقول جسم الطلب

المثال 1: الحد الأدنى للطلب (`text` + `format=mp3`)

المثال 2: استخدام نبرة صوت مستنسخة `reference_id`

المثال 3: استنساخ صوت فوري لمرة واحدة (`references`)

المثال 3: ضبط سرعة الكلام / مستوى الصوت (`prosody`)

المثال 5: تبديل النموذج + التحكم في معدل البت

المثال 6: شكل موجة PCM الخام

رد الاتصال غير المتزامن (`callback_url`)

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

الخلاصة