تحويل النص إلى كلام المتزامن v3

أنشئ الصوت بشكل متزامن أو أنشئ مهام غير متزامنة قابلة للاسترداد عبر HTTP v3.

HTTP TTS v3 هو العقد المحايد الموصى به. تتولى المنصة توجيه المزوّد، ويستخدم العميل voiceId و modelId العامّين.

Base URL

https://fishaudio.org/api/open/v3

اختيار التسليم المتزامن أو غير المتزامن

استخدم الوضع المتزامن للنص القصير، وJobs للنص الطويل أو الدُفعات أو النتائج التي يجب استردادها.

اكتشاف النماذج والأصوات

curl "https://fishaudio.org/api/open/v3/speech/tts/capabilities"
curl "https://fishaudio.org/api/open/v3/voices?page=1&pageSize=20&includePersonal=false" \
  -H "Authorization: Bearer $FISHAUDIO_API_KEY"

استخدم نموذجًا متاحًا وصوتًا تتضمن modelIds الخاصة به النموذج المختار. اقرأ الحدود والصيغ وعناصر التحكم من capabilities.

التوليد المتزامن

POST /api/open/v3/speech/tts

curl "https://fishaudio.org/api/open/v3/speech/tts" \
  -H "Authorization: Bearer $FISHAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: tts-example-001" \
  -d '{"text":"Hello","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s21pro-flash","format":"mp3"}' --output speech.mp3

حقول الطلب

field	type	required	constraints
`text`	string	yes	1–10,000
`voiceId`	string	yes	must support `modelId`
`modelId`	string	no	public model ID; omitted uses voice provider default
`format`	string	no	`mp3`, `wav`, `ogg`; default `mp3`
`speed`	number	no	0.5–2; default 1
`volume`	number	no	-20–20; default 0
`pitch`	number	no	-12–12
`stability`	number	no	0.5–1.5
`similarity`	number	no	0.5–1.5
`language`	string	no	1–64 characters in v3
`emotion`	string	no	1–64 characters in v3
`instruction`	string	no	up to 1,600 characters
`textNormalization`	boolean	no	structured-text normalization

Unknown fields are rejected. Unsupported generic controls are listed in X-OpenAPI-Ignored-Parameters.

الاستجابة الناجحة

HTTP/1.1 200 OK
Content-Type: audio/mpeg
X-Request-Id: tts-example-001
X-OpenAPI-Quota-Remaining: 99994
X-OpenAPI-Credits-Used: 6

<binary audio data>

تعيد الاستجابة الناجحة بيانات صوتية ثنائية. افحص حالة HTTP ثم Content-Type؛ الأخطاء بصيغة JSON.

المهام غير المتزامنة

POST /speech/tts/jobs
GET /speech/tts/jobs/{jobId}
GET /speech/tts/jobs/{jobId}/audio?download=1
Authorization: Bearer FISHAUDIO_API_KEY

احفظ task.taskId. الحالتان pending وprocessing غير نهائيتين؛ success وpartial_fail وfail نهائية.

الأخطاء وإعادة المحاولة

Errors use {"code":"ERR_REQUEST_ID_CONFLICT","message":"...","requestId":"..."}. 400 طلب غير صالح؛ 401 مفتاح غير صالح؛ 402 حصة غير كافية؛ 404 غير موجود؛ 409 تعارض؛ 413 كبير؛ 429 حد المعدل؛ 500 فشل.

منع التكرار والفوترة

أعد استخدام X-Request-Id ثابت فقط للطلب نفسه. لا يعاد إرسال الصوت المتزامن المكتمل، بينما تبقى Jobs قابلة للاستعلام.

العقد المقروء آليًا والترحيل

GET /api/open/v3/openapi.json

يظل عملاء v1/v2 متوافقين. تستخدم التكاملات الجديدة v3. Migration guide.

تحويل النص إلى كلام المتزامن v3

في هذه الصفحة