Foleyix · API v1

API ドキュメント

Foleyix の有料プランでサーバーやスクリプトから非公開 WAV 音声を生成。

連携ルール

Creator、Studio、Ultra に API を含みます。ウェブ、CLI、API は秒数、保存容量、キューを共有します。

契約終了後は新規生成とキー作成を停止。既存タスクと保存期間内のダウンロードは継続し、更新で生成を再開。

サーバー連携専用。ブラウザーのクロスオリジン呼び出し、Webhook、参照音声、プロジェクト 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 /jobs`	cursor、limit、active=1 で自分の単独タスクを一覧表示。
`GET /jobs/{id}`	状態、実際の長さ、保存期限、結果の有無を確認。
`GET /jobs/{id}/audio`	GET、HEAD、単一バイト範囲で WAV を取得。
`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 ダウンロード

GET、HEAD、単一バイト範囲で WAV を取得。

ダウンロードにも Bearer 認証が必要です。URLは非公開で保存期限まで有効。公開プロバイダーリンクへの転送はありません。

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

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

契約終了後は新規生成とキー作成を停止。既存タスクと保存期間内のダウンロードは継続し、更新で生成を再開。

今すぐ保存してください。キー全体は一度だけ表示されます。サーバーに保管し、公開しないでください。