Foleyix · API v1

Документация API

Создавайте приватные WAV на сервере с платной подпиской Foleyix.

Правила интеграции

Creator, Studio и Ultra включают API. Сайт, 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 включают API. Сайт, 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. URL приватный, действует до конца хранения и не перенаправляет на публичный адрес провайдера.

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

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

Сохраните ключ сейчас. Полное значение показывается один раз. Храните на сервере и не публикуйте.