---
title: "API 개요와 키"
description: "Filmsquare REST API의 기본 URL, API 키나 세션을 쓰는 인증, 키 만드는 방법, 규칙, 만나게 될 오류를 알려 드려요."
url: https://www.filmsquare.ai/docs/ko/api/overview/
lang: ko
section: api
updated: 2026-11-10
---

# API 개요와 키

스튜디오가 하는 모든 일은 REST API 하나를 거쳐요. 나도 그대로 쓸 수 있어요. 앱, 내 Claude, 내 스크립트가 모두 같은 경로를 같은 역할과 같은 규칙으로 호출해요.

| | |
| --- | --- |
| 기본 URL | `https://app.filmsquare.ai/v1` |
| 형식 | HTTPS 위의 JSON |
| 인증 | `Authorization: Bearer <API key or session token>` |
| 레퍼런스 | `https://app.filmsquare.ai/v1/openapi.json`(OpenAPI 3.1, 공개). [OpenAPI 레퍼런스](https://www.filmsquare.ai/docs/ko/api/openapi/)를 보세요 |

## 인증

공개 경로 몇 개(`GET /v1/pricing`, `POST /v1/signup`, 웹훅 수신 경로)를 뺀 모든 경로에는 베어러 토큰이 필요해요.

- **API 키**는 `fsk_`로 시작해요. 키는 사람 한 명(또는 에이전트 계정)에게, **워크스페이스 하나**에 속하고, 키의 역할로 움직여요. 그 사람의 현재 역할보다 높을 수는 없어요.
- **세션 토큰**은 로그인한 사람의 것이에요(웹 앱이 보내는 것).

```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. 스튜디오에서 사이드바 맨 위의 워크스페이스 메뉴를 열고 **Settings**, 그다음 **Claude**를 선택해요.
2. **Use a personal key instead**를 선택하고 이름을 지은 다음 **Create a personal key**를 선택해요.
3. 키를 복사해요. 키는 한 번만 보여요.

개인 키는 그 워크스페이스에서 내 역할을 가져요. 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`가 한 번만 들어 있어요. Filmsquare는 해시만 보관해요. 키의 역할은 내 역할보다 높을 수 없어요. `userId`로 워크스페이스 멤버인 에이전트 계정의 키를 만들 수도 있어요.

`GET /workspaces/{ws}/api-keys`는 키 목록(접두사만)을 보여 주고, `POST /workspaces/{ws}/api-keys/{id}/revoke`는 하나를 폐기해요. 키로는 키를 만들 수 없어요. 이 경로는 로그인한 사람이나 워크스페이스 키가 필요하고, 개인 키나 Claude 연결은 `403 not_a_person`으로 거부돼요.

## 역할

경로마다 최소 역할이 있어요. `owner` > `producer` > `director` > `maker` > `reviewer` > `viewer` 순이에요. 그보다 낮은 호출은 `{"required": "director", "actual": "maker"}`와 함께 `403 insufficient_role`을 받아요. 볼 수 없는 행은 존재하지 않는 행과 똑같이 `404`로 답해요. [스태프, 역할, 접근 권한](https://www.filmsquare.ai/docs/ko/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가 OK로 이어진 테이크 하나당 비용이 가장 낮은 모델로 보내요. 폴링하는 대신 [웹훅](https://www.filmsquare.ai/docs/ko/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/ko/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` | 웹훅이나 가져오기 URL이 공개 http(s) 주소가 아니에요 | — |
| 401 | `unauthenticated` | 토큰이 없거나, 폐기되었거나 만료됐어요 | — |
| 402 | `out_of_credits` | 이 테이크에 쓸 수 있는 크레딧이 부족해요 | `needed`, `available`(크레딧) |
| 402 | `plan_limit` | 요금제에 포함되지 않아요: 무료의 파이널, 두 번째 작품, 저장 공간, 인원, 요금제 없는 팩 | `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` | 이 팀의 컨펌 담당자가 아니에요 | — |
| 403 | `role_exceeds_caller` | 내 역할보다 높은 역할의 초대나 키 | — |
| 403 | `not_a_person` | 개인 키나 Claude 연결로 키를 관리하려 했어요 | — |
| 404 | `not_found` | 행이 없거나, 볼 수 없어요 | — |
| 409 | `gate_closed` | 게이트가 열리기 전의 파이널 | `episode_id`, `waiting_on`(팀, 또는 어느 에피소드에도 없는 컷은 `placement`) |
| 409 | `changed_since` | 더 이상 현재 버전이 아닌 버전을 컨펌했어요 | `version`(현재 버전) |
| 409 | `already_signed_off` | 단계가 이미 컨펌됐어요 | — |
| 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}}}
```

## 관련 문서

- [웹훅](https://www.filmsquare.ai/docs/ko/api/webhooks/)
- [OpenAPI 레퍼런스](https://www.filmsquare.ai/docs/ko/api/openapi/)
- [Claude가 할 수 있는 일](https://www.filmsquare.ai/docs/ko/claude/tools/): MCP로 쓰는 같은 API
