Fish TTS API توضيح الاتصال

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

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

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

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

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

رأس الطلب

الرأس	مطلوب	الشرح
`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` هو عنوان URL 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	لا	عنوان رد الاتصال غير المتزامن، انظر أدناه “رد الاتصال غير المتزامن”. هذا هو امتداد نسبي للواجهة الرسمية。

استنساخ لمرة واحدة يقبل فقط عنوان URL للصوت عبر HTTPS، ولا يقبل MessagePack، Base64، data URI أو URL مع بيانات الاعتماد. يُوصى بأن يكون طول الصوت المرجعي من 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://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3"
}

audio_url تشير إلى CDN الخاص بالمنصة، يمكن تنزيلها مباشرة عبر GET أو تشغيلها في <audio>. ستعيد الاستجابة الناجحة النهائية أيضًا cost في المستوى الأعلى، حيث amount هو الرصيد الفعلي المخصوم؛ إذا كان هناك خصم على الحساب، فإن 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://platform2.cdn.acedata.cloud/fish/b6f161f2-a100-4818-add2-47694f234659.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://platform2.cdn.acedata.cloud/fish/6220d605-39d0-4d43-9e58-0f12949dc9b9.mp3",
      "text": "春天的清晨，阳光穿过树叶，落在安静的小路上。"
    }]
  }'

استجابة ناجحة تم اختبارها:

{
  "audio_url": "https://platform2.cdn.acedata.cloud/fish/995dfe37-b187-474d-8323-b08d6678ed8f.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://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.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://platform2.cdn.acedata.cloud/fish/7e7abf3d-3d72-4c9f-8eb6-8af932d7c96e.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://platform2.cdn.acedata.cloud/fish/64adc04b-c196-4a0f-9070-222ba101ce6c.wav"
}

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

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

也可以用 Fish Tasks API 主动按 task_id 拉取结果；终态记录的 response.cost 与回调中的 cost 一致，详见该文档。

错误处理

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"
}

参数校验错误会在 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

الهوية

وكيل

متقدم

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`）

错误处理

结论