6.0 API6.1 APIの概要とキー
APIの概要とキー
FilmsquareのREST API。ベースURL、APIキーまたはセッションによる認証、キーのつくり方、規約、出会うエラーを説明します。
Studioが行うことは、すべて1つのREST APIを通っていて、ご自身でも使えます。アプリ、お手持ちのClaude、スクリプトは、すべて同じルートを、同じ役割、同じルールで呼びます。
| ベースURL | https://app.filmsquare.ai/v1 |
| 形式 | HTTPS上のJSON |
| 認証 | Authorization: Bearer <APIキーまたはセッショントークン> |
| リファレンス | https://app.filmsquare.ai/v1/openapi.json(OpenAPI 3.1、公開)。OpenAPIリファレンスをご覧ください |
認証 #
少数の公開ルート(GET /v1/pricing、POST /v1/signup、webhookの受信側)を除くすべてのルートで、Bearerトークンが必要です。
- APIキー:
fsk_で始まります。キーは、1つのワークスペースの、1人(またはエージェントのユーザー)に属し、キーの役割で動きます。その人の現在の役割を超えることはありません。 - セッショントークン:ログイン中の人のトークンです(Webアプリが送るものです)。
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_… # your key
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
GET /meは、呼び出した人が誰か、キーで入ったかどうか、所属するワークスペースを返します。ワークスペースのルートは、すべてパスにワークスペースのidを含みます:/v1/workspaces/{ws}/…。
キーを入手する #
個人のキー(どの役割でも) #
- Studioで、サイドバー上部にあるワークスペースメニューを開き、Settings、Claudeの順に選びます。
- Use a personal key insteadを押し、名前を付けて、Create a personal keyを押します。
- キーをコピーします。表示されるのは、1回だけです。
個人のキーは、そのワークスペースでのご自身の役割をもちます。Claude Code向けにつくられていますが、キーの管理を除いて、役割で許されるすべてのAPI呼び出しに使えます。
ワークスペースのAPIキー(プロデューサー以上) #
プロデューサーまたはオーナーは、ログインしたうえで、APIから、役割を指定してキーをつくれます。
curl -s -X POST "$FS/workspaces/$WS/api-keys" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "content-type: application/json" \
-d '{"name": "Render farm sync", "role": "maker"}'
レスポンスに、完全なkeyが1回だけ含まれます。Filmsquareが保存するのは、そのハッシュだけです。キーの役割が、ご自身の役割を超えることはありません。userIdを指定すると、ワークスペースのメンバーであるエージェントのユーザー向けのキーをつくれます。
GET /workspaces/{ws}/api-keysでキーを一覧できます(プレフィックスのみ)。POST /workspaces/{ws}/api-keys/{id}/revokeで1つを失効させます。キーでキーをつくることはできません。これらのルートは、ログイン中の人かワークスペースのキーを必要とし、個人のキーやClaudeの接続は、403 not_a_personで拒否されます。
役割 #
ルートごとに最低の役割があります。owner > producer > director > maker > reviewer > viewerの順です。それより下の役割からの呼び出しは、{"required": "director", "actual": "maker"}つきの403 insufficient_roleになります。見てはいけない行は、存在しない行と同じ404で返ります。スタッフ、役割、アクセス権をご覧ください。
最初のセッション #
# Your productions
curl -s "$FS/workspaces/$WS/projects" -H "Authorization: Bearer $FS_KEY"
# An episode's steps and the finals gate
curl -s "$FS/workspaces/$WS/episodes/$EP/steps" -H "Authorization: Bearer $FS_KEY"
# Price a draft of a shot before making it
curl -s -X POST "$FS/workspaces/$WS/shots/$SHOT/estimate" \
-H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
-d '{"kind": "video", "tier": "draft"}'
# Make it (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"}'
# Follow it
curl -s "$FS/workspaces/$WS/generations?shotId=$SHOT&order=desc&limit=5" \
-H "Authorization: Bearer $FS_KEY"
kindは、keyframe、video、dialogue、sfx、musicのいずれかです。tierは、draftまたはfinalです。いまのところ、sfxとmusicをつくる接続済みのモデルはありません。これらのテイクは、アップロードで入れます(createUploadTicketのあと、対象のレイヤーを指定してcompleteUpload)。modelKeyを省略すると、Filmsquareは、採用テイク1本あたりの費用がいちばん低い、対応可能なモデルに振り分けます。ポーリングする代わりに、webhookを購読してください。
規約 #
| 項目 | ルール |
|---|---|
| フィールド名 | レスポンスはsnake_case、リクエストボディはcamelCase |
| 一覧 | {"items": […], "next_cursor": "…"}。次のページにはcursorを渡します。limitは200まで、orderはascまたはdesc |
| アーカイブした行 | includeArchived=trueを指定しない限り、一覧から外れます |
| 削除 | 行は削除ではなくアーカイブされます(POST …/{id}/archive)。バージョン、採用、OK、費用は変更されません |
| 冪等性 | 生成のリクエストは、Idempotency-Keyヘッダー(またはボディのidempotencyKey)を受け取ります。同じキーなら、すでにある生成が返ります |
| 金額 | 費用はクレジットで、作業が始まった時点のレートです。1クレジットのユーロでの価格は、GET /v1/pricingとクレジットと費用にあります |
出会うエラー #
エラーはどれも、同じ形をしています。
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
| ステータス | コード | 発生する場面 | details |
|---|---|---|---|
| 400 | validation_error | ボディ、クエリ、パスパラメータがスキーマに合わない | 検証エラーの一覧 |
| 400 | bad_request、invalid_value | ルートがリクエストを拒否した、またはデータベースが値を読めない(不正なidなど) | — |
| 400 | url_not_allowed | webhookまたは取り込みのURLが、公開のhttp(s)アドレスではない | — |
| 401 | unauthenticated | トークンがない、または失効または期限切れ | — |
| 402 | out_of_credits | このテイクに使えるクレジットが足りない | needed、available(クレジット) |
| 402 | plan_limit | プランに含まれない:Freeでの本番、2つめの作品、ストレージ、シート、プランなしでのクレジットパック | limit(final、productions、storage、seats、packs)、plan |
| 402 | budget_exceeded | エピソードの予算(エピソードのbudgetCredits)を超える | episodeId、budgetCredits、spent、inFlight、needed(クレジット) |
| 403 | insufficient_role | 呼び出した人の役割が、ルートの最低の役割より下 | required、actual |
| 403 | not_a_signer | この部署のOK担当ではない | — |
| 403 | role_exceeds_caller | 自分より上の役割での招待またはキー | — |
| 403 | not_a_person | 個人のキーまたはClaudeの接続で、キーを管理しようとした | — |
| 404 | not_found | 行が存在しない、または見る権限がない | — |
| 409 | gate_closed | 関門が開く前の本番 | episode_id、waiting_on(部署。どのエピソードにもないカットはplacement) |
| 409 | changed_since | 現在のものではなくなったバージョンにOKを出した | version(現在のもの) |
| 409 | already_signed_off | 工程はすでにOK済み | — |
| 409 | element_version_frozen | テイクがすでに使ったバージョンに、リファレンスを追加した | — |
| 409 | conflict | 同じ値の行がすでにある | — |
| 422 | foreign_key_violation、check_violation、not_null_violation | 参照先の行がない(または別のワークスペースにある)、またはデータベースのルールが値を拒否した | constraint、table、detail |
402 out_of_creditsは、次のようになります。
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
"details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
関連ページ #
- Webhook
- OpenAPIリファレンス
- Claudeでできること:同じAPIをMCP経由で