6.0 API6.1 API 개요와 키
API 개요와 키
Filmsquare REST API의 기본 URL, 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 레퍼런스를 보세요 |
인증 #
공개 경로 몇 개(GET /v1/pricing, POST /v1/signup, 웹훅 수신 경로)를 뺀 모든 경로에는 베어러 토큰이 필요해요.
- API 키는
fsk_로 시작해요. 키는 사람 한 명(또는 에이전트 계정)에게, 워크스페이스 하나에 속하고, 키의 역할로 움직여요. 그 사람의 현재 역할보다 높을 수는 없어요. - 세션 토큰은 로그인한 사람의 것이에요(웹 앱이 보내는 것).
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}/….
키 받기 #
개인 키(모든 역할) #
- 스튜디오에서 사이드바 맨 위의 워크스페이스 메뉴를 열고 Settings, 그다음 Claude를 선택해요.
- Use a personal key instead를 선택하고 이름을 지은 다음 Create a personal key를 선택해요.
- 키를 복사해요. 키는 한 번만 보여요.
개인 키는 그 워크스페이스에서 내 역할을 가져요. 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가 한 번만 들어 있어요. 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로 답해요. 스태프, 역할, 접근 권한을 보세요.
첫 세션 #
# 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로 이어진 테이크 하나당 비용이 가장 낮은 모델로 보내요. 폴링하는 대신 웹훅을 구독하세요.
규칙 #
| 주제 | 규칙 |
|---|---|
| 필드 이름 | 응답은 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 | 웹훅이나 가져오기 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는 이렇게 생겼어요.
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
"details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
관련 문서 #
- 웹훅
- OpenAPI 레퍼런스
- Claude가 할 수 있는 일: MCP로 쓰는 같은 API