Filmsquare

API

スタジオを、APIとして。

FilmsquareのREST APIは、スタジオとスタッフのClaudeが使っているものと同じAPIで、お手元のスクリプトからも使えます。HTTPSのJSON、ルートから生成するOpenAPI 3.1のドキュメント1つ、人とワークスペースごとのベアラーキー、テイクの準備ができたときの署名つきWebhookです。

curl -s "$FS/me" \
  -H "Authorization: Bearer $FS_KEY"
リクエストを送るGET /v1/me

ベースURLと認証

キー1つ、役割1つ、ワークスペース1つ

呼び出しにはすべてAuthorization: Bearer <token>をつけます。fsk_で始まるAPIキーか、ログイン済みのセッションです。ワークスペースのルートは、パスにワークスペースを含みます。/v1/workspaces/{ws}/…

ベースURL
https://app.filmsquare.ai/v1
最初の呼び出し
export 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"}'
  1. owner
  2. producer
  3. director
  4. maker
  5. reviewer
  6. viewer

キーにスコープはありません。キーの力は、ひとつのワークスペースでの役割そのもので、背後にいる人の役割を超えることはありません。

キー方法
個人キー「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"]}'
1回の配信
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を返します。
ステータスコードいつ
400validation_errorボディ、クエリ、パスのパラメータが、スキーマに合っていない
401unauthenticatedトークンがない、または失効・期限切れ
402out_of_creditsこのテイクに使えるクレジットが足りない
402plan_limitプランに含まれない。たとえばFreeでの本番
402budget_exceededエピソードのクレジット予算を超えてしまう
403insufficient_role役割が、ルートのx-min-roleに届いていない
403account_blockedアカウントが停止されており、すべてのリクエストが拒否される
404not_foundその行は存在しないか、見る権限がない
409gate_closed待っている部署のOKが出る前の本番
409workspace_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は公開されており、クレジットの価格、シートの価格、繰り越し、パックを返します。