Foleyix · API v1

وثائق API

أنشئ صوت WAV خاصًا من خادمك باستخدام اشتراك Foleyix المدفوع.

قواعد التكامل

تشمل Creator وStudio وUltra الواجهة. يتشارك الموقع وCLI وAPI الثواني والتخزين والطابور.

عند انتهاء الاشتراك يتوقف التوليد وإنشاء المفاتيح. تستمر المهام الحالية وتبقى النتائج المحفوظة متاحة؛ يعيد التجديد التوليد.

تكامل الخادم فقط. لا يدعم استدعاءات المتصفح عبر المصادر أو Webhook أو الأصوات المرجعية أو المشاريع الاحترافية.

المصادقة

Authorization: Bearer <API_KEY>

احفظ المفتاح الآن. تظهر قيمته الكاملة مرة واحدة فقط. احتفظ به على خادمك ولا تنشره.

https://foleyix.com/api/v1

إرسال ← متابعة ← تنزيل

أرسل Idempotency-Key فريدًا (1–128 حرفًا) لكل توليد. أعد المحاولة بالمفتاح والمدخل نفسه حتى بعد تبديل مفتاح API؛ يعيد المدخل المختلف 409.

تابع كل 5 ثوانٍ على الأقل. queued/running قيد العمل؛ succeeded/failed/unknown تنهي المتابعة. انتهاء المهلة أو unknown لا يبرر إنشاء مهمة جديدة تلقائيًا.

curl --fail-with-body https://foleyix.com/api/v1/generations \
  -H "Authorization: Bearer $FOLEYIX_API_KEY" \
  -H "Idempotency-Key: my-audio-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A quiet forest with birds singing, 3 seconds.","mode":"ambience"}'

curl ↓Node.js ↓Python ↓

المسار

المسار	السلوك
`POST /generations`	إرسال prompt وmode اختياري؛ يعيد مهمة مع HTTP 202.
`GET /jobs`	عرض مهامك المستقلة باستخدام cursor وlimit وactive=1.
`GET /jobs/{id}`	عرض الحالة والمدة الفعلية وموعد الحفظ وتوفر النتيجة.
`GET /jobs/{id}/audio`	تنزيل WAV باستخدام GET أو HEAD ونطاق بايت واحد.
`GET /quota`	عرض ثواني التوليد والتخزين والطابور وصلاحية التوليد.

cursor · limit: 1–100 (50) · active: 0 | 1

أوضاع التوليد

free · narration · dialogue · podcast · scene · sfx · ambience

استخدم 1–3,000 حرف Unicode. الوضع الافتراضي free؛ اختيار الوضع لا يعيد كتابة النص.

الحصة المشتركة

تشمل Creator وStudio وUltra الواجهة. يتشارك الموقع وCLI وAPI الثواني والتخزين والطابور.

GET /api/v1/quota
quota.generationLimit / generationUsed / generationReserved
quota.availableGenerationSeconds / generationAllowed
quota.storageLimit / storageUsed
quota.queueUsed / queueLimit

حدود الطلبات

حتى 300 طلب و20 إرسال توليد في الدقيقة لكل حساب، وتشترك جميع المفاتيح في العد.

429 · Retry-After: seconds

حتى 5 مفاتيح نشطة لكل حساب.

الأخطاء وحالات المهام

{"error":{"code":"paid_subscription_required","message":"…"},"requestId":"…"}
X-Request-ID: …
400 invalid_input · 401 invalid_api_key · 403 paid_subscription_required
404 job_not_found · 409 request_key_conflict / result_not_ready
410 audio_expired · 429 rate_limited · 503 api_unavailable

تنزيل WAV الخاص

تنزيل WAV باستخدام GET أو HEAD ونطاق بايت واحد.

يتطلب التنزيل أيضًا مصادقة Bearer. الرابط خاص وينتهي مع مدة الحفظ ولا يعيد التوجيه إلى رابط عام للمزود.

GET /api/v1/jobs/{id}/audio
Authorization: Bearer <API_KEY>
Range: bytes=0-43

job.durationSeconds / bytes / resultAvailable
job.resultExpiresAt / downloadUrl

احفظ المفتاح الآن. تظهر قيمته الكاملة مرة واحدة فقط. احتفظ به على خادمك ولا تنشره.