Foleyix · API v1

Documentation API

Générez des WAV privés depuis votre serveur avec votre abonnement Foleyix.

Règles d’intégration

Creator, Studio et Ultra incluent l’API. Le site, CLI et API partagent secondes, stockage et capacité de file.

À expiration, les nouvelles générations et clés sont bloquées. Les tâches existantes continuent et les sons conservés restent téléchargeables ; le renouvellement rétablit la génération.

Intégrations serveur uniquement. Pas d’appels navigateur interorigines, webhooks, voix de référence ou projets professionnels.

Authentification

Authorization: Bearer <API_KEY>

Enregistrez cette clé maintenant. Elle ne sera affichée qu’une fois. Gardez-la sur votre serveur, sans la publier.

https://foleyix.com/api/v1

Envoyer → suivre → télécharger

Utilisez une Idempotency-Key unique (1–128 caractères) par génération. Réessayez avec la même clé et la même entrée, même après rotation ; une entrée différente retourne 409.

Interrogez au moins toutes les 5 secondes. queued/running sont en cours ; succeeded/failed/unknown terminent le suivi. Un délai dépassé ou unknown ne justifie pas une nouvelle tâche automatique.

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 ↓

Point d’accès

Point d’accès	Comportement
`POST /generations`	Envoyer un prompt et un mode facultatif ; retourne une tâche avec HTTP 202.
`GET /jobs`	Lister vos tâches indépendantes avec cursor, limit et active=1.
`GET /jobs/{id}`	Consulter l’état, la durée réelle, la conservation et la disponibilité.
`GET /jobs/{id}/audio`	Télécharger le WAV avec GET, HEAD et une plage d’octets unique.
`GET /quota`	Consulter les secondes, le stockage, la file et les droits actuels.

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

Modes de génération

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

Utilisez 1–3 000 caractères Unicode. Le mode par défaut est free ; le choix du mode ne réécrit pas le prompt.

Quota partagé

Creator, Studio et Ultra incluent l’API. Le site, CLI et API partagent secondes, stockage et capacité de file.

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

Limites de requêtes

Maximum 300 requêtes et 20 soumissions de génération par minute et par compte, partagées entre toutes les clés.

429 · Retry-After: seconds

5 clés actives maximum par compte.

Erreurs et états

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

Interrogez au moins toutes les 5 secondes. queued/running sont en cours ; succeeded/failed/unknown terminent le suivi. Un délai dépassé ou unknown ne justifie pas une nouvelle tâche automatique.

Téléchargements WAV privés

Télécharger le WAV avec GET, HEAD et une plage d’octets unique.

Les téléchargements exigent aussi l’authentification Bearer. L’URL reste privée, expire avec la conservation et ne redirige jamais vers un lien public du fournisseur.

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

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

À expiration, les nouvelles générations et clés sont bloquées. Les tâches existantes continuent et les sons conservés restent téléchargeables ; le renouvellement rétablit la génération.

Enregistrez cette clé maintenant. Elle ne sera affichée qu’une fois. Gardez-la sur votre serveur, sans la publier.