Filmsquare

API

스튜디오를 API로.

Filmsquare의 REST API는 스튜디오와 내 Claude가 쓰는 바로 그 API예요. 이제 내 스크립트에도 열려 있어요. HTTPS 위의 JSON, 라우트에서 자동으로 생성되는 OpenAPI 3.1 문서 하나, 사람과 워크스페이스마다 발급하는 Bearer 키, 테이크가 완료되면 받는 서명된 웹훅이 있어요.

curl -s "$FS/me" \
  -H "Authorization: Bearer $FS_KEY"
요청 보내기GET /v1/me

기본 URL과 인증

키 하나, 역할 하나, 워크스페이스 하나

모든 호출에는 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'

웹훅

폴링 대신 구독하세요

프로듀서 이상만 가능하고, whsec_ 시크릿은 한 번만 보여 줘요. 2xx로 응답해 주세요. 5xx, 429, 타임아웃이면 Filmsquare가 지수 백오프로 재시도해요. 간격은 약 2초에서 최대 10분, 최대 8번이에요. x-fs-delivery는 재시도해도 그대로예요. 웹훅

이벤트발송 시점
generation.succeeded테이크 렌더가 끝났을 때
generation.failed렌더가 실패했을 때
take.selected컷이나 씬에서 테이크가 OK컷으로 선택됐을 때
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"]}'
웹훅 전송 한 건
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), 정렬은 order(asc 또는 desc)로 지정해요.
멱등성테이크 요청은 Idempotency-Key 헤더를 받아요. 같은 키로 요청하면 같은 테이크가 돌아와요.
삭제행은 보관 처리될 뿐 삭제되지 않아요. 버전, OK컷, 컨펌, 비용은 절대 바뀌지 않아요.
보이지 않음볼 수 없는 행을 요청하면 존재하지 않는 행과 똑같이 404가 돌아와요.
상태코드시점
400validation_error본문, 쿼리, 경로 파라미터가 스키마와 맞지 않을 때
401unauthenticated토큰이 없거나 폐기·만료된 경우
402out_of_credits이 테이크에 쓸 크레딧이 부족해요
402plan_limit요금제에 포함되지 않은 경우(예: 무료 요금제의 파이널)
402budget_exceeded에피소드 예산(크레딧)을 넘게 될 때
403insufficient_role내 역할이 라우트의 x-min-role보다 낮은 경우
403account_blocked계정이 정지되었어요. 모든 요청이 거부돼요
404not_found행이 없거나, 볼 수 없는 경우
409gate_closed대기 중인 팀이 컨펌하기 전에 파이널을 요청했을 때
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개의 유로 가격, 1인당 요금과 1인당 크레딧, 이월, 저장 공간, 크레딧 팩을 돌려줘요. 요금의 바탕이 되는 숫자들이에요.

종료 상태
curl -s https://app.filmsquare.ai/v1/pricing

자주 묻는 질문

스튜디오가 쓰는 API와 같은 건가요?

네. 스튜디오, 내 Claude, 내 스크립트가 같은 라우트를 같은 역할과 같은 규칙으로 호출해요.

API 키에 스코프가 있나요?

아니요. 키는 워크스페이스 하나에서 역할 하나로 동작하고, 발급한 사람의 역할보다 높아질 수 없어요. 역할이 곧 권한 범위예요.

레퍼런스는 어디 있나요?

https://app.filmsquare.ai/v1/openapi.json의 OpenAPI 3.1 문서는 공개돼 있고 라우트에서 바로 생성되니까 라우트와 어긋나는 일이 없어요.

테이크가 완료된 건 어떻게 알 수 있나요?

웹훅을 generation.succeeded에 구독하세요. 전송에는 x-fs-signature로 서명이 붙고, 5xx, 429, 타임아웃이면 재시도해요.

컨펌 전에 스크립트로 파이널을 렌더할 수 있나요?

아니요. 게이트가 열리기 전의 파이널 요청에는 대기 중인 팀 목록과 함께 409 gate_closed가 돌아와요.

키 없이도 요금을 볼 수 있나요?

네. GET https://app.filmsquare.ai/v1/pricing은 공개 API이고 크레딧 가격, 1인당 요금, 이월, 크레딧 팩을 돌려줘요.