وظائف غير متزامنة

استخدم مهام TTS غير المتزامنة للنص الطويل وإنشاء الدُفعات وسير العمل بنمط خطاف الويب وتدفقات واجهة المستخدم حيث يمكن للمستخدمين مغادرة الصفحة بينما لا يزال الصوت قيد المعالجة.

إنشاء وظيفة

POST /api/open/v1/speech/tts/jobs
Authorization: Bearer FISHAUDIO_API_KEY
Content-Type: application/json

طلب

{
  "text": "Hello from Fish Audio.",
  "voiceId": "00a1b221-6137-4b73-ad62-b0cbce134167",
  "modelId": "fishaudio-s21pro-flash",
  "format": "mp3"
}

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

يستخدم المثال اختبار النظام العام الصوتي 00a1b221-6137-4b73-ad62-b0cbce134167. استبدله بالمعرف الصوتي المفضل لديك بعد التحقق من الاتصال.

curl https://fishaudio.org/api/open/v1/speech/tts/jobs \
  -H "Authorization: Bearer FISHAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from Fish Audio.","voiceId":"00a1b221-6137-4b73-ad62-b0cbce134167","modelId":"fishaudio-s21pro-flash","format":"mp3"}'

إجابة

تعيد نقطة نهاية الإنشاء 202 Accepted. احفظ task.id قبل بدء الاستعلام.

{
  "task": {
    "id": "task_123",
    "status": "pending",
    "audioUrl": null,
    "delivery": { "downloadUrl": null, "downloadReady": false }
  },
  "record": { "id": "task_123", "status": "pending" },
  "requestId": "req_123",
  "quotaRemaining": 99994,
  "creditsUsed": 6
}

احصل على وظيفة

GET /api/open/v1/speech/tts/jobs/{taskId}
Authorization: Bearer FISHAUDIO_API_KEY

قيم الحالة هي pending وprocessing وsuccess وpartial_fail وfail.

GET /api/open/tts/jobs/{taskId}/audio?download=1
Authorization: Bearer FISHAUDIO_API_KEY

تتطلب روابط task.segments[].playbackUrl الترويسة نفسها. لا تنشئ مهمة جديدة لاستعادة تنزيل.

استعادة معرف مهمة مفقود

إذا وصل طلب الإنشاء إلى الخادم ولكن العميل لم يستلم استجابة 202 Accepted، فاعرض المهام الحديثة أولاً:

curl "https://fishaudio.org/api/open/v1/speech/tts/jobs?limit=20&createdAfter=2026-07-20T00%3A00%3A00Z" \
  -H "Authorization: Bearer FISHAUDIO_API_KEY"

تُرتّب النتائج من الأحدث إلى الأقدم. استخدم createdAt وtextFingerprint وvoiceId وengineModelId لمطابقة الطلب المحلي. تدعم الواجهة page وlimit (بحد أقصى 100) وstatus وcreatedAfter بتنسيق ISO 8601. تعرض القائمة معاينة للنص فقط ولا تعرض النص الكامل. بعد استعادة taskId، تابع الاستعلام عن المهمة الحالية. عرض القائمة لا يستهلك حصة API.

الفواتير والائتمانات

يحجز الخادم creditsUsed مرة واحدة عند قبول المهمة. لا يؤدي الاستقصاء أو التنزيل أو تكرار تنزيل الصوت نفسه إلى خصم جديد. تتم إعادة رصيد المهمة المدفوعة مسبقًا والفاشلة عبر مسار استرداد متكرر وآمن.

بالنسبة للدفعة، قم بضبط التزامن على جانبك وتحقق من الملف الشخصي قبل إضافة عدد كبير من المهام. إذا فشلت إحدى المهام بسبب عدم كفاية الاعتمادات، فقم بإيقاف rest الخاص بالدُفعة مؤقتًا حتى يقوم مالك الحساب بحل الرصيد.

أخطاء