FreeLipSync API ドキュメント

始める前に

FreeLipSync REST API を使い、お手持ちの音声からリップシンク動画、写真が話す動画、ミュージックビデオを生成できます。登録済みアカウント、Agent コンソールで作成した API Key、API クレジットが必要です。既存ユーザーを含むすべてのアカウントに、初めて Agent コンソールの残高を読み込んだとき、または有効な動画生成リクエストを送信したときに、30 クレジットを一度だけ付与します。追加分は購入できます。メンバーシップに定期的な API クレジットの付与はありません。利用できるモデル、音声の長さ、アカウントで共有するタスク制限は会員プランによって決まります。

このガイドでは https://freelipsync.com/api/v1 を使用します。 ステージングでテストする場合は、FLS_BASE_URL をその環境のオリジンに設定し、同じ環境でキーを作成します。 そのデプロイメントでは API アクセスを有効にする必要があります。 この例では、短い speech.mp3 と顔が 1 人写った face.jpg を使用します。

機械可読なリクエストおよびレスポンスのスキーマについては、OpenAPI リファレンスを開く。 エージェントをご希望ですか? MCPセットアップガイドを参照してください。

認証と最初のリクエスト

Agent コンソールでキーを作成し、作成ダイアログからコピーします。 完全なシークレットは一度だけ表示されます。 ブラウザー コードやパブリック リポジトリではなく、環境変数に保存します。 紛失した場合は、それを取り消して、別のものを作成します。 すべてのキーは同じアカウント残高と制限を使用します。 別のキーを作成しても同時実行性は向上しません。

export FLS_BASE_URL='https://freelipsync.com'
export FLS_API_KEY='YOUR_API_KEY'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FLS_API_KEY" \
  "$FLS_BASE_URL/api/v1/capabilities"

REST は API Key を受け入れます。 MCP に対して発行された OAuth アクセス トークンは、/mcp に対してのみ有効であり、REST に対しては有効ではありません。 成功した応答は、結果を data でラップし、request_id を含みます。 エラーには代わりに error と request_id が表示されます。 ID は不透明な文字列で、クレジット金額は 10 進数の文字列です。

{"data":{"id":"YOUR_ASSET_ID","kind":"image","status":"processing","poll_after_seconds":5,"expires_at":"2026-10-21T00:00:00.000Z"},"request_id":"REQUEST_ID"}

これは例示的な素材応答であり、機能要求に対する応答ではありません。 ファイルを準備する前に、返された機能を読んで、現在のアカウントのモデル max_audio_seconds、アップロード バイト/MIME の制限およびタスクの制限を確認します。

生成ワークフロー

1. 機能を取得し、画像またはビデオと入力音声をアップロードします。
2. それぞれの直接アップロードを確認し、両方のアセットが ready になるまで待ちます。
3. アセット ID と生成モードを使用して見積を作成します。 total_points と expires_at を確認してください。
4. 安定した冪等性キーを使用してその見積もりを送信します。 これによりタスクが受け入れられ、クレジットが保持されます。
5. poll_after_seconds を使用して返されたジョブ ID をポーリングするか、Webhook を受信します。
6. 完了したら、署名された URL からダウンロードします。 処理に失敗した場合、元の確保額を返還します。

アセットと見積もりの作成には、クレジットが消費されたり、ビデオ ジョブが作成されたりすることはありません。 生成が受け入れられると、キャンセルすることはできません。 処理が失敗した場合のみクレジットが返されます。 クライアントのタイムアウトは、タスクが失敗したことを証明するものではありません。

ローカルファイルをアップロードするか、URLをインポートします

ローカル ファイルの場合、POST /assets は署名付き PUT URL を返します。 API Key を使用せずに、返された upload.headers を使用して生のファイル バイトを送信します。 次に、{} を使用して POST /assets/{id}/confirm を呼び出し、GET /assets/{id} をポーリングします。 awaiting_upload および processing は準備ができていません。 failed は失敗の終端状態です。 サーバーのポーリング アドバイスを使用します。

{
  "kind":"image",
  "source":{
    "type":"upload",
    "filename":"face.jpg",
    "content_type":"image/jpeg",
    "size_bytes":123456
  }
}

size_bytes は、この例の数値ではなく、実際のバイト数である必要があります。 画像、ビデオ、オーディオ入力には異なる MIME とサイズ制限があります。 真実の情報源として GET /capabilities を使用してください。 ファイル拡張子だけでは有効性が判断されません。

パブリックにアクセス可能な HTTPS URL をインポートすることもできます。 これは非同期です。準備が整うまで、返されたアセットをポーリングします。 Web サイトの Cookie を必要とするローカル パス、file:// URL、プライベート ネットワーク URL または URL は、使用可能なソースではありません。 署名付きソース URL を使用する場合は、フェッチされるまで十分な時間を与えてください。

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FLS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-import-UNIQUE-REQUEST-ID' \
  --data '{"kind":"image","source":{"type":"url","url":"https://YOUR-PUBLIC-HOST/face.jpg"}}' \
  "$FLS_BASE_URL/api/v1/assets"

3 番目のルートは、{"kind":"image"} を含む POST /asset-upload-sessions です。ユーザーに browser_upload_url を返し、asset_id を保持し、ブラウザーにアップロードした後にポーリングします。 これは、ローカル ファイルを読み取れないクライアントに役立ちます。 アップロード チケットと署名付き URL は一時的な認証情報です。 ログやチャット記録に公開しないでください。

完全なコード例

以下から cURL、Python、または JavaScript を選択してください。 各例では、同じアップロード→見積もり→送信→投票→ダウンロードのワークフローを実行し、見積もりを印刷し、クレジットを使用する前に質問します。 長い例は折りたたまれています。 「コピー」ボタンは常に完全なプログラムをコピーします。

• cURL: Bash、cURL、jq、および Python 3 (UUID の場合)。 Bash スクリプトとして保存し、実行します。
• Python: Python 3 と requests ライブラリを使います。python -m pip install requests でインストールしてください。
• JavaScript: Node.js 20+ および内蔵モジュールのみ。 quickstart.mjs として保存し、node quickstart.mjs を実行します。

上記の環境変数をエクスポートし、face.jpg および speech.mp3 を作業ディレクトリに配置します。 公開 Web ページではなく、サーバーまたは開発マシン上で実行します。 署名されたアップロード/ダウンロード リクエストには、API Key が含まれることはありません。 スクリプトは HTTP エラーで停止します。 受け入れられた可能性のある送信を新しいキーで再開するのではなく、再試行する前に以下の回復ルールを確認してください。

# Requires bash, curl and jq. Set these before running:
# export FLS_API_KEY='YOUR_API_KEY'
# export FLS_BASE_URL='https://freelipsync.com'  # or your staging origin
# Place face.jpg and speech.mp3 in this directory.
set -euo pipefail
: "${FLS_API_KEY:?Set FLS_API_KEY first}"
BASE="${FLS_BASE_URL:-https://freelipsync.com}/api/v1"
RUN="$(python3 -c 'import uuid; print(uuid.uuid4())')"
request() {
  curl --fail-with-body --silent --show-error \
    -H "Authorization: Bearer $FLS_API_KEY" "$@"
}
wait_ready() {
  local id="$1" row status
  for ((i=0; i<120; i++)); do
    row="$(request "$BASE/assets/$id")"

モデル、オプション、クレジット

すべてのモードでは、アップロードされた運転オーディオ アセットが必要です。 テキスト読み上げ、音声複製、およびキャンセルは、この API のパラメーターではありません。 Image Super / Motion Control には Starter または Pro が必要です。 クレジットを購入するだけでは有効になりません。 モデル固有の例外を含む、モデルの可用性と期間制限の機能を確認します。

サーバーで確認した音声の長さを秒単位で切り上げ、最低 5 秒として課金します。5 秒の見積もりは Image Fast が 5 クレジット、Image Max が 10、Image Super または Music Video が 15 です。見積もりの作成だけでは残高を引き落としません。送信時に見積額を確保し、成功時に同額を消費します。処理失敗時には確保した額を返還します。生成後の料金変更はありません。購入クレジットはメンバーシップと別管理で、有効期限はなく、現金での返金はできません。

{
  "mode":"image_super",
  "face_asset_id":"READY_IMAGE_ID",
  "audio_asset_id":"READY_AUDIO_ID",
  "options":{"motion":{"action":"Smile gently","camera":"Static camera"}}
}

Music Video の場合は、mode: "music_video" と以下の MV 設定を使用します。 version は 1.0 または 1.1 を受け入れます。 ratio は、21:9、16:9、4:3、1:1、3:4 または 9:16 を受け入れます。 resolution は 480p または 720p を受け入れます。 デフォルトは、1.0、16:9、および 480p です。 ライブスキーマの機能を確認します。 モーション オプションを別のモードにアタッチしたり、内部 Web モデル エイリアスを送信したりしないでください。

{
  "mode":"music_video",
  "face_asset_id":"READY_IMAGE_ID",
  "audio_asset_id":"READY_AUDIO_ID",
  "options":{"mv":{"version":"1.0","ratio":"16:9","resolution":"480p","style":{"directorial":"A calm performance","artistic":"Warm evening light"}}}
}

エンドポイントリファレンス

以下のパスは、/api/v1 に対する相対パスです。 すべてのビジネスコールには認証が必要です。

リストのデフォルトは 20 項目、最大値は 50. 変更せずに data.next_cursor を渡し、次のページをフェッチします。 複数のアクティブなジョブの場合は、それぞれを個別にポーリングするのではなく、1 つのリスト要求でカンマ区切りの ids を使用します。 このリストは API/MCP クレジット ジョブに関するものであり、古い Web サイト ジョブの一般的なリストではありません。

冪等性、エラー、レート制限

個別の書き込み操作ごとに新しい Idempotency-Key を使用し、その操作を再試行するときに同じキーとペイロードを保持します。 キーは、8 ～ 128 の可視 ASCII 文字です。 新しいユーザーリクエストには新しいキーが必要です。 再試行は行われません。 この例では、送信前に引用符とキーのペアを出力します。 運用環境では、送信前にそのペアを永続化し、返されたジョブ ID を永続化します。 不確実な送信後にサンプル全体を再起動しないでください。新しいキーが作成されてしまいます。

見積もりは 10 分で期限切れになります。 受諾前に明確な拒否を行うと、リクエストを修正したり、新たな見積もりを取得したりすることができます。 応答が不確かな場合は、最初に元の試行を回復する必要があります。 受け入れられたタスクを再生すると、2 番目の借方なしで元のジョブが返されます。 異なるキーで見積を 2 回使用することはできません。

REST と MCP は、アカウントごとの読み取り/補助バケットを共有します: Free 30, Starter 30, Pro 60 リクエスト/分。 補助呼び出しには、アップロード、確認、見積もりが含まれます。 poll_after_seconds と Retry-After のどちらか長い待ち時間が必要な方を尊重してください。 Web サイトのステータスの読み取りは個別に管理されます。 生成頻度とビデオ実行容量は、Web サイト、REST、および MCP 全体で共有されます。 Web サイトと API/MCP には、それぞれ独立した未完了タスク許容量があります: プールごとに Free 1, Starter 3, Pro 10。 REST と MCP は、すべてのキーと OAuth 接続を含む API/MCP プールを共有します。 追加の認証情報によってそれが増えることはありません。 ワークフローの例については、API/MCP を使用する理由 を参照してください。

結果とオプションの Webhook

ジョブのステータスは、queued、processing、completed、または failed です。 アプリケーションがタイムアウトになった場合でもジョブ ID を保持します。 タイムアウトが発生してもサーバー タスクはキャンセルされません。 成功したら、有効な間に output.download_url を使用します。 作業が保持されている間に、ジョブまたはダウンロード エンドポイントを再フェッチして、更新されたリンクを取得します。 繰り返しダウンロードしてもクレジットは消費されません。 保持期間は、別個の API のみの期間ではなく、アカウントの通常の作業保持期間に従います。 出力は透かしのないオリジナルの品質であり、ソースの権利と条件に従って商業的に使用できます。

サーバー統合の場合は、Agent コンソール → 詳細で Webhook エンドポイントを作成し、送信時にその ID を webhook_endpoint_id として渡します。 エンドポイントは、まずプレーンテキストの応答本文としてチャレンジを含む endpoint.verification POST に応答する必要があります。 この設定では、パブリック認証情報管理 API ではなく、Web サイト コンソールを使用します。

Webhook イベントには、event_id、event_type、occurred_at、generation_id、および data が含まれます。 ダウンロード リンクは Webhook ペイロードから省略されます。 新しいリンクをジョブにクエリします。 エンドポイント シークレットを使用し、FLS-Webhook-Timestamp のタイムスタンプを使用して、raw リクエスト本文: HMAC-SHA256 または timestamp + "." + body に対して FLS-Webhook-Signature を検証します。 v1= 署名を一定時間内に照合し、最近のタイムスタンプを適用してリプレイを拒否します。 event_id / FLS-Webhook-Id によって重複を除去し、速やかに 2xx を返します。 重複した通知によって、別の生成や 2 番目のビジネス アクションがトリガーされてはなりません。 最も単純な最初の統合としてポーリングを続けます。

HTTP の代わりにアシスタントを介して作業する必要がありますか? エージェントで MCP をセットアップ、または Agent コンソール に戻ります。