Foleyix · API v1

API 接入文档

使用 Foleyix 付费订阅，从服务器或脚本生成私有 WAV 音频。

接入规则

Creator、Studio、Ultra 均包含 API。网站、CLI 和 API 共用秒数、存储及队列容量。

订阅到期后停止新生成和创建密钥。已有任务继续执行，保留期内音频仍可下载；续费恢复生成。

仅用于服务端接入。首版不提供跨域浏览器调用、Webhook、参考音操作或专业项目接口。

鉴权

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 /jobs`	使用 cursor、limit 和 active=1 查询本人独立生成任务。
`GET /jobs/{id}`	查询状态、实际时长、保留期和结果可用性。
`GET /jobs/{id}/audio`	下载 WAV，支持 GET、HEAD 和单段字节 Range。
`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

轮询间隔至少 5 秒。queued/running 表示处理中；succeeded/failed/unknown 停止轮询。超时或 unknown 不应自动重新创建任务。

私有 WAV 下载

下载 WAV，支持 GET、HEAD 和单段字节 Range。

音频下载始终需要 Bearer 鉴权。下载地址私有，随保留期失效，不会跳转到公开供应商链接。

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

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

订阅到期后停止新生成和创建密钥。已有任务继续执行，保留期内音频仍可下载；续费恢复生成。

现在保存此密钥，完整值仅显示一次。请保存在服务器端，切勿公开。