Fish TTS API توضيح الربط

هذا الواجهة تعتمد على Fish Audio الرسمية TTS API، فقط في طريقة التوثيق (استخدام توكن هذه المنصة) والرد غير المتزامن (callback_url كامتداد) هناك اختلاف، هيكل جسم الطلب متطابق مع المصدر. العنوان هو POST https://api.acedata.cloud/fish/tts.

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

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

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

📘 الوثائق الكاملة: 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`	object[]	لا	عينات مرجعية مضمنة، الهيكل مطابق للمصدر، كل عنصر يحتوي على `audio` و `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	لا	عنوان رد غير متزامن، انظر أدناه “الرد غير المتزامن”. هذا هو امتداد بالنسبة للواجهة الرسمية。

أسماء الحقول متطابقة تمامًا مع المصدر. باستثناء callback_url، المعاني والقيم الأخرى راجع وثائق TTS الرسمية من Fish.

مثال 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://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}

audio_url تشير إلى CDN الخاص بالمنصة، يمكن تنزيلها مباشرة باستخدام GET أو تشغيلها في <audio>。الرابط متاح لفترة طويلة، ولكن يُنصح بالاحتفاظ بنسخة في تخزينك الخاص.

مثال 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://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.mp3"
}

مثال 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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3"
}

speed أكبر من 1 يسرع، أقل من 1 يبطئ؛ volume وحدة dB، 0 تعني عدم التغيير، الأعداد الموجبة زيادة، السالبة تقليل.

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

من خلال رأس 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": "معدل بت عالي mp3",
    "format": "mp3",
    "mp3_bitrate": 128
  }'

返回（实测）：

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

示例 5：PCM 原始波形

需要在浏览器里做实时拼接、或在客户端做后续处理（混音、变速）的场景，推荐使用 pcm：

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

返回（实测）：

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

链接的扩展名跟随请求里的 format：mp3 得到 .mp3，wav 与 pcm 得到 .wav（WAV 容器，16 بت PCM）。

异步回调（`callback_url`）

长文本一次合成可能需要十几秒到几十秒，连接如果中断需要重试。请求体中传 callback_url 后，接口会立即返回 {task_id, started_at}，上游真正完成时把完整结果以 POST JSON 形式回调到该 URL，请求体中带同一个 task_id。

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://platform2.cdn.acedata.cloud/fish/bd66b8c5-7543-4557-b684-baa72407e336.mp3"
}

也可以用 Fish Tasks API 主动按 task_id 拉取结果，详见该文档。

错误处理

400 token_mismatched：请求参数缺失或不合法（最常见是 text 为空，或 format 传了 mp3/wav/pcm 之外的值）。
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"
}

参数校验错误会把上游的 pydantic 报错原文放在 message 字段，便于定位是哪个字段不合法，例如：

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

结论

接入 Fish TTS 的最小代价是：在已有调用 api.fish.audio/v1/tts 的代码里把鉴权换成本平台 token，并在请求体里显式带上 format: "mp3"。长文本场景建议使用 callback_url 异步回调；对克隆音色 reference_id 的发现，请配合 Fish Model Query 与 Fish Model Get。

البداية

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

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

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

الصوت الذكي

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

CAPTCHA

الهوية

وكيل

متقدم

Fish TTS API توضيح الربط

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

رأس الطلب

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

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

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

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

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

示例 5：PCM 原始波形

异步回调（`callback_url`）

错误处理

结论

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

​رأس الطلب

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

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

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

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

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

​示例 5：PCM 原始波形

​异步回调（callback_url）

​错误处理

​结论

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

رأس الطلب

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

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

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

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

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

示例 5：PCM 原始波形

异步回调（`callback_url`）

错误处理

结论