Foleyix · API v1

API 문서

유료 Foleyix 구독으로 서버 또는 스크립트에서 비공개 WAV 오디오를 생성하세요.

API 키 →OpenAPI 3.1

통합 규칙

Creator, Studio, Ultra에는 API 접근이 포함됩니다. 웹사이트, CLI, API는 생성 시간(초), 저장소 및 대기열 용량을 공유합니다.

만료 시 새로운 생성과 키 생성이 중단됩니다. 기존 작업은 계속되며 보관된 오디오는 다운로드할 수 있습니다. 갱신하면 생성 기능이 복구됩니다.

서버 전용 통합입니다. 브라우저 교차 출처 호출, 웹훅, 참조 음성, 전문 프로젝트 엔드포인트는 지원하지 않습니다.

인증

Authorization: Bearer <API_KEY>

지금 이 키를 저장하세요. 한 번만 표시됩니다. 서버에 보관하고 절대 공개하지 마세요.

https://foleyix.com/api/v1

제출 → 폴링 → 다운로드

생성을 시도할 때마다 고유한 Idempotency-Key(1–128자)를 전송하세요. 자격 증명을 교체한 후에도 동일한 키와 동일한 입력으로 재시도하세요. 입력이 변경되면 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프롬프트와 선택적 모드를 제출하면 HTTP 202와 함께 작업이 반환됩니다.
GET /jobscursor, limit, active=1을 사용하여 독립 작업을 나열합니다.
GET /jobs/{id}상태, 실제 길이, 보관 기간 및 결과 사용 가능 여부를 조회합니다.
GET /jobs/{id}/audioWAV 다운로드; GET, HEAD 및 단일 바이트 범위 지원.
GET /quota생성 시간(초), 저장소, 대기열 및 현재 권한을 조회합니다.

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

생성 모드

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

1–3,000개의 유니코드 문자를 사용하세요. 기본 모드는 무료이며, 모드를 선택해도 프롬프트가 다시 작성되지 않습니다.

공유 할당량

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

최소 5초 간격으로 폴링하세요. queued/running은 진행 중이며, succeeded/failed/unknown은 폴링을 종료합니다. 시간 초과나 unknown은 다른 작업을 생성할 수 있는 권한이 아닙니다.

비공개 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

만료 시 새로운 생성과 키 생성이 중단됩니다. 기존 작업은 계속되며 보관된 오디오는 다운로드할 수 있습니다. 갱신하면 생성 기능이 복구됩니다.

지금 이 키를 저장하세요. 한 번만 표시됩니다. 서버에 보관하고 절대 공개하지 마세요.