API
スタジオを、APIとして。
FilmsquareのREST APIは、スタジオとスタッフのClaudeが使っているものと同じAPIで、お手元のスクリプトからも使えます。HTTPSのJSON、ルートから生成するOpenAPI 3.1のドキュメント1つ、人とワークスペースごとのベアラーキー、テイクの準備ができたときの署名つきWebhookです。
curl -s "$FS/me" \
-H "Authorization: Bearer $FS_KEY"
WEBHOOK · POST /filmsquare/hook

S3-B5-05Seedance 2.5 · 本番1080p · 5秒 · 105.30クレジット · €5.27
ベースURLと認証
キー1つ、役割1つ、ワークスペース1つ
呼び出しにはすべてAuthorization: Bearer <token>をつけます。fsk_で始まるAPIキーか、ログイン済みのセッションです。ワークスペースのルートは、パスにワークスペースを含みます。/v1/workspaces/{ws}/…
https://app.filmsquare.ai/v1export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_…
# Who you are, and your workspaces
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
# A draft take of a shot (the same Idempotency-Key never makes it twice)
curl -s -X POST "$FS/workspaces/$WS/shots/$SHOT/generations" \
-H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
-H "Idempotency-Key: shot-$SHOT-draft-1" \
-d '{"kind": "video", "tier": "draft"}'ownerproducerdirectormakerreviewerviewer
キーにスコープはありません。キーの力は、ひとつのワークスペースでの役割そのもので、背後にいる人の役割を超えることはありません。
| キー | 方法 |
|---|---|
| 個人キー | 「Settings → Claude → Use a personal key instead」から。ご自身の役割で、表示されるのは一度だけです。 |
| ワークスペースキー | POST /workspaces/{ws}/api-keysは、プロデューサーかオーナーが、名前と役割をつけて作ります。表示されるのは一度だけで、保存されるのはハッシュだけです。 |
| 無効にする | POST /workspaces/{ws}/api-keys/{id}/revoke。そのキーでの次の呼び出しは、401 api_key_revokedを返します。 |
OPENAPI 3.1
呼び出しも仕事も、名前はひとつ
GET https://app.filmsquare.ai/v1/openapi.jsonは公開されており、OpenAPI 3.1で、ルートそのものから生成されます。どのルートにもoperationIdがあり、Claudeがrun_actionで実行するときと同じ名前です。スクリプトで呼ぶ操作と、Claudeに任せる仕事が、同じものになります。x-min-roleは、呼び出せる最も低い役割を示します。OpenAPIリファレンス · Claude向けMCP
"/workspaces/{ws}/shots/{id}/generations": {
"post": {
"operationId": "generateForShot",
"x-min-role": "maker",
…
}
}curl -s https://app.filmsquare.ai/v1/openapi.json | jq '.paths | keys | length'WEBHOOK
ポーリングせず、購読する
プロデューサー以上。whsec_のシークレットは一度だけ表示されます。2xxで応答してください。5xx、429、タイムアウトのときは、Filmsquareが指数バックオフで再試行します。間隔は約2秒から最大10分、最大8回までです。x-fs-deliveryは再試行しても変わりません。Webhook
| イベント | 送信のタイミング |
|---|---|
generation.succeeded | テイクのレンダリングが完了した |
generation.failed | レンダリングが失敗した |
take.selected | カットまたはシーンでテイクが採用された |
asset_version.created | レンダリングで、アセットの新しいバージョンができた |
["*"] | 全イベント |
curl -s -X POST "$FS/workspaces/$WS/webhooks" \
-H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
-d '{"url": "https://example.com/filmsquare/hook", "events": ["generation.succeeded", "take.selected"]}'POST /filmsquare/hook
content-type: application/json
x-fs-signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with whsec_…>
x-fs-event: generation.succeeded
x-fs-delivery: generation.succeeded:9b2e…決まりごととエラー
エラーの形式はひとつ
| トピック | ルール |
|---|---|
| フィールド名 | レスポンスはsnake_case、リクエストボディはcamelCaseです。 |
| 一覧 | 一覧は{"items": […], "next_cursor": "…"}の形で返します。次のページはcursor、件数はlimit(最大200)、並びはasc/descで指定します。 |
| Idempotency | テイクのリクエストはIdempotency-Keyヘッダーを受け付けます。同じキーなら、同じテイクが返ります。 |
| 削除 | 行はアーカイブされるだけで、削除されません。バージョン、採用テイク、OK、費用は変わりません。 |
| 閲覧できない行 | 見る権限のない行は、存在しない行と同じく404を返します。 |
| ステータス | コード | いつ |
|---|---|---|
| 400 | validation_error | ボディ、クエリ、パスのパラメータが、スキーマに合っていない |
| 401 | unauthenticated | トークンがない、または失効・期限切れ |
| 402 | out_of_credits | このテイクに使えるクレジットが足りない |
| 402 | plan_limit | プランに含まれない。たとえばFreeでの本番 |
| 402 | budget_exceeded | エピソードのクレジット予算を超えてしまう |
| 403 | insufficient_role | 役割が、ルートのx-min-roleに届いていない |
| 403 | account_blocked | アカウントが停止されており、すべてのリクエストが拒否される |
| 404 | not_found | その行は存在しないか、見る権限がない |
| 409 | gate_closed | 待っている部署のOKが出る前の本番 |
| 409 | workspace_paused | ワークスペースが一時停止中:新しいテイクやツールは開始されない |
{"error": {"code": "gate_closed",
"message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}GET /v1/pricingはキーが不要です。クレジット1つのユーロ価格、シートの価格とシートに付くクレジット、繰り越し、ストレージ、クレジットパックを返します。料金の元になる数字です。
curl -s https://app.filmsquare.ai/v1/pricingよくある質問
スタジオが使っているAPIと同じですか?
はい。スタジオも、スタッフ自身のClaudeも、お手元のスクリプトも、同じルートを、同じ役割と同じ決まりで呼びます。
APIキーにスコープはありますか?
いいえ。キーは、ひとつのワークスペースでひとつの役割として働き、作成した人の役割を超えることはありません。役割が、そのままスコープです。
リファレンスはどこですか?
https://app.filmsquare.ai/v1/openapi.jsonのOpenAPI 3.1ドキュメントは公開されており、ルートから生成されるので、ルートとずれることはありません。
テイクの準備ができたかは、どうやってわかりますか?
generation.succeededにWebhookを登録します。配信にはx-fs-signatureで署名がつき、5xx、429、タイムアウトのときは再試行されます。
OKの前に、スクリプトから本番をレンダリングできますか?
いいえ。関門が開く前の本番には、409 gate_closedを返し、待っている部署を添えます。
キーなしで料金を読めますか?
はい。GET https://app.filmsquare.ai/v1/pricingは公開されており、クレジットの価格、シートの価格、繰り越し、パックを返します。