Filmsquare ヘルプドキュメント

6.0 API6.1 APIの概要とキー

APIの概要とキー

FilmsquareのREST API。ベースURL、APIキーまたはセッションによる認証、キーのつくり方、規約、出会うエラーを説明します。

更新日 2分で読めます.md

このページの内容
  1. 認証
  2. キーを入手する
  3. 個人のキー(どの役割でも)
  4. ワークスペースのAPIキー(プロデューサー以上)
  5. 役割
  6. 最初のセッション
  7. 規約
  8. 出会うエラー
  9. 関連ページ

Studioが行うことは、すべて1つのREST APIを通っていて、ご自身でも使えます。アプリ、お手持ちのClaude、スクリプトは、すべて同じルートを、同じ役割、同じルールで呼びます。

ベースURLhttps://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}/…。

キーを入手する #

個人のキー(どの役割でも) #

  1. Studioで、サイドバー上部にあるワークスペースメニューを開き、Settings、Claudeの順に選びます。
  2. Use a personal key insteadを押し、名前を付けて、Create a personal keyを押します。
  3. キーをコピーします。表示されるのは、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
400validation_errorボディ、クエリ、パスパラメータがスキーマに合わない検証エラーの一覧
400bad_request、invalid_valueルートがリクエストを拒否した、またはデータベースが値を読めない(不正なidなど)—
400url_not_allowedwebhookまたは取り込みのURLが、公開のhttp(s)アドレスではない—
401unauthenticatedトークンがない、または失効または期限切れ—
402out_of_creditsこのテイクに使えるクレジットが足りないneeded、available(クレジット)
402plan_limitプランに含まれない:Freeでの本番、2つめの作品、ストレージ、シート、プランなしでのクレジットパックlimit(final、productions、storage、seats、packs)、plan
402budget_exceededエピソードの予算(エピソードのbudgetCredits)を超えるepisodeId、budgetCredits、spent、inFlight、needed(クレジット)
403insufficient_role呼び出した人の役割が、ルートの最低の役割より下required、actual
403not_a_signerこの部署のOK担当ではない—
403role_exceeds_caller自分より上の役割での招待またはキー—
403not_a_person個人のキーまたはClaudeの接続で、キーを管理しようとした—
404not_found行が存在しない、または見る権限がない—
409gate_closed関門が開く前の本番episode_id、waiting_on(部署。どのエピソードにもないカットはplacement)
409changed_since現在のものではなくなったバージョンにOKを出したversion(現在のもの)
409already_signed_off工程はすでにOK済み—
409element_version_frozenテイクがすでに使ったバージョンに、リファレンスを追加した—
409conflict同じ値の行がすでにある—
422foreign_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}}}

このページのMarkdown: /docs/ja/api/overview.md