Foleyix · API v1

API documentation

Generate private WAV audio from your server or scripts with your paid Foleyix subscription.

Integration rules

Creator, Studio and Ultra include API access. Website, CLI and API share seconds, storage and queue capacity.

At expiry, new generation and key creation stop. Existing tasks continue and retained audio remains downloadable; renewal restores generation.

Server integrations only. No browser cross-origin calls, webhooks, reference voices or professional project endpoints.

Authentication

Authorization: Bearer <API_KEY>

Save this key now. It is shown only once. Keep it on your server and never publish it.

https://foleyix.com/api/v1

Submit → poll → download

Send a unique Idempotency-Key (1–128 characters) for each intended generation. Retry with the same key and identical input, even after rotating credentials; changed input returns 409.

Poll at least 5 seconds apart. queued/running are in progress; succeeded/failed/unknown end polling. A timeout or unknown is not permission to create another task.

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	Behavior
`POST /generations`	Submit prompt and optional mode; returns a task with HTTP 202.
`GET /jobs`	List your standalone tasks with cursor, limit and active=1.
`GET /jobs/{id}`	Query status, actual duration, retention and result availability.
`GET /jobs/{id}/audio`	Download WAV; GET, HEAD and a single byte range.
`GET /quota`	Read generation seconds, storage, queue and current permission.

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

Generation modes

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

Use 1–3,000 Unicode characters. The default mode is free; choosing a mode does not rewrite your prompt.

Shared allowance

Creator, Studio and Ultra include API access. Website, CLI and API share seconds, storage and queue capacity.

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

Request limits

Up to 300 requests and 20 generation submissions per minute per account, shared by all keys.

429 · Retry-After: seconds

Up to 5 active keys per account.

Errors & task states

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

Poll at least 5 seconds apart. queued/running are in progress; succeeded/failed/unknown end polling. A timeout or unknown is not permission to create another task.

Private WAV downloads

Download WAV; GET, HEAD and a single byte range.

Audio downloads always require the same Bearer authentication. The URL is private, expires with retention, and never redirects to a public provider link.

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

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

At expiry, new generation and key creation stop. Existing tasks continue and retained audio remains downloadable; renewal restores generation.

Save this key now. It is shown only once. Keep it on your server and never publish it.