Foleyix · API v1

Documentación API

Genera WAV privados desde tu servidor con tu suscripción Foleyix.

Reglas de integración

Creator, Studio y Ultra incluyen API. Sitio, CLI y API comparten segundos, almacenamiento y cola.

Al vencer, se detienen nuevas generaciones y claves. Las tareas existentes continúan y el audio conservado puede descargarse; renovar restaura la generación.

Solo integración de servidor. Sin llamadas de navegador entre orígenes, webhooks, voces de referencia ni proyectos profesionales.

Autenticación

Authorization: Bearer <API_KEY>

Guarda esta clave ahora. Solo se muestra una vez. Consérvala en tu servidor y no la publiques.

https://foleyix.com/api/v1

Enviar → consultar → descargar

Envía una Idempotency-Key única (1–128 caracteres) por generación. Reintenta con la misma clave y entrada, incluso tras rotarla; una entrada diferente devuelve 409.

Consulta cada 5 segundos como mínimo. queued/running están en curso; succeeded/failed/unknown finalizan la consulta. Un tiempo agotado o unknown no permite recrear automáticamente la tarea.

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 ↓

Endpoint

Endpoint	Comportamiento
`POST /generations`	Enviar prompt y modo opcional; devuelve tarea con HTTP 202.
`GET /jobs`	Listar tus tareas independientes con cursor, limit y active=1.
`GET /jobs/{id}`	Consultar estado, duración real, conservación y disponibilidad.
`GET /jobs/{id}/audio`	Descargar WAV con GET, HEAD y un único rango de bytes.
`GET /quota`	Consultar segundos, almacenamiento, cola y permiso actual.

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

Modos de generación

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

Usa 1–3.000 caracteres Unicode. El modo predeterminado es free; elegir un modo no modifica tu prompt.

Cuota compartida

Creator, Studio y Ultra incluyen API. Sitio, CLI y API comparten segundos, almacenamiento y cola.

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

Límites de solicitudes

Hasta 300 solicitudes y 20 envíos de generación por minuto y cuenta, compartidos entre todas las claves.

429 · Retry-After: seconds

Máximo de 5 claves activas por cuenta.

Errores y estados

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

Consulta cada 5 segundos como mínimo. queued/running están en curso; succeeded/failed/unknown finalizan la consulta. Un tiempo agotado o unknown no permite recrear automáticamente la tarea.

Descargas WAV privadas

Descargar WAV con GET, HEAD y un único rango de bytes.

Las descargas también requieren autenticación Bearer. La URL es privada, vence con la retención y nunca redirige a enlaces públicos del proveedor.

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

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

Al vencer, se detienen nuevas generaciones y claves. Las tareas existentes continúan y el audio conservado puede descargarse; renovar restaura la generación.

Guarda esta clave ahora. Solo se muestra una vez. Consérvala en tu servidor y no la publiques.