> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Fish voice generation API guide - Ace Data Cloud

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

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

لاستخدام Fish TTS API، يجب أولاً الذهاب إلى [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على توكن API الخاص بك، احتفظ به للاستخدام لاحقًا.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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

**توكن API واحد يكفي لاستدعاء جميع خدمات المنصة، ولا حاجة لتقديم طلب منفصل لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ عند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [لوحة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [Fish TTS API →](https://platform.acedata.cloud/services/fish)

## رأس الطلب

| 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` أو `pcm`。حتى لو كانت الوثائق الرسمية تدرج `wav`、`opus`، ستعيد هذه الواجهة `400 Input should be 'pcm' or 'mp3'`。 |                                                                                                                                                                                                              |
| `reference_id` | string    | string\[] | لا                                                                                                                                                                                           | معرف الصوت المستنسخ (يمكن إنشاؤه بواسطة [Fish Model API](https://platform.acedata.cloud/documents/fish-model) أو استرجاعه في [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)）。 |
| `references`   | object\[] | لا        | عينات مرجعية مضمنة، الهيكل مطابق للمصدر، كل عنصر يحتوي على `audio` و `text`。واحد من `reference_id` أو `references` يجب أن يُستخدم.                                                           |                                                                                                                                                                                                              |
| `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`، المعاني والقيم الأخرى يمكن الاطلاع عليها في [وثائق Fish الرسمية TTS](https://docs.fish.audio/text-to-speech/text-to-speech).

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

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

الرد (تم الاختبار):

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/05f81919f2e04e35bb404a88fb177854.mp3"
}
```

`audio_url` هو رابط مباشر لـ Fish R2، يمكن تنزيله مباشرة باستخدام GET أو تشغيله في `<audio>`، التوقيع عادةً يكون صالحًا لمدة ساعة واحدة، يُنصح بنقله بعد ذلك إلى تخزين الكائنات الخاص بك.

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

فيما يلي استخدام صوت إسباني عام على منصة Fish (`_id` يمكن استرجاعه من [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)):

```shell theme={null}
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"
  }'
```

الرد (تم الاختبار):

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/560078cf603d4584a2313ca4cd742056.mp3"
}
```

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

```shell theme={null}
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"
  }'
```

الرد (تم الاختبار):

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/f16759a3335748f1b4d1e56ed54d81dd.mp3"
}
```

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

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

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

```shell theme={null}
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
  }'
```

返回（实测）：

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/6b660348776e40529e537aa30b1051d2.mp3"
}
```

## 示例 5：PCM 原始波形

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

```shell theme={null}
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
  }'
```

返回（实测）：

```json theme={null}
{
  "audio_url": "https://platform.r2.fish.audio/task/2052cc1f33b049d99a18fcc496f4462e.mp3"
}
```

> 当前响应链接的扩展名固定为 `.mp3`，实际内容为请求中指定 `format` 的字节流。下载时应根据请求里的 `format` 决定如何解析。

## 异步回调（`callback_url`）

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

```shell theme={null}
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"
  }'
```

立即返回（实测）：

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "started_at": "2026-05-11T01:23:04.742Z"
}
```

稍后 `callback_url` 会收到形如：

```json theme={null}
{
  "task_id": "79d82713-2897-4eeb-9934-e7544d471aa7",
  "audio_url": "https://platform.r2.fish.audio/task/b627c2f7d38a4083a837570ba6d0962f.mp3"
}
```

也可以用 [Fish Tasks API](https://platform.acedata.cloud/documents/fish-tasks) 主动按 `task_id` 拉取结果，详见该文档。

## 错误处理

* `400 token_mismatched`：请求参数缺失或不合法（最常见是漏传 `format`、`text` 为空）。
* `401 invalid_token`：鉴权 token 不存在或无效。
* `429 too_many_requests`：触发账号速率限制。
* `500 api_error`：服务器内部错误。

错误响应示例：

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

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

```json theme={null}
{
  "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](https://platform.acedata.cloud/documents/fish-model-query) 与 [Fish Model Get](https://platform.acedata.cloud/documents/fish-model-get)。