---
title: "APIの概要とキー"
description: "FilmsquareのREST API。ベースURL、APIキーまたはセッションによる認証、キーのつくり方、規約、出会うエラーを説明します。"
url: https://www.filmsquare.ai/docs/ja/api/overview/
lang: ja
section: api
updated: 2026-11-10
---

# 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リファレンス](https://www.filmsquare.ai/docs/ja/api/openapi/)をご覧ください |

## 認証

少数の公開ルート（`GET /v1/pricing`、`POST /v1/signup`、webhookの受信側）を除くすべてのルートで、Bearerトークンが必要です。

- **APIキー**：`fsk_`で始まります。キーは、**1つ**のワークスペースの、1人（またはエージェントのユーザー）に属し、キーの役割で動きます。その人の現在の役割を超えることはありません。
- **セッショントークン**：ログイン中の人のトークンです（Webアプリが送るものです）。

```bash
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から、役割を指定してキーをつくれます。

```bash
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`で返ります。[スタッフ、役割、アクセス権](https://www.filmsquare.ai/docs/ja/working-together/crew-and-roles/)をご覧ください。

## 最初のセッション

```bash
# 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](https://www.filmsquare.ai/docs/ja/api/webhooks/)を購読してください。

## 規約

| 項目 | ルール |
| --- | --- |
| フィールド名 | レスポンスは`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`と[クレジットと費用](https://www.filmsquare.ai/docs/ja/concepts/credits-and-costs/)にあります |

## 出会うエラー

エラーはどれも、同じ形をしています。

```json
{"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`は、次のようになります。

```json
{"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](https://www.filmsquare.ai/docs/ja/api/webhooks/)
- [OpenAPIリファレンス](https://www.filmsquare.ai/docs/ja/api/openapi/)
- [Claudeでできること](https://www.filmsquare.ai/docs/ja/claude/tools/)：同じAPIをMCP経由で
