Filmsquare 도움말문서

6.0 API6.1 API 개요와 키

API 개요와 키

Filmsquare REST API의 기본 URL, API 키나 세션을 쓰는 인증, 키 만드는 방법, 규칙, 만나게 될 오류를 알려 드려요.

업데이트 4분 분량.md

이 페이지 목차
  1. 인증
  2. 키 받기
  3. 개인 키(모든 역할)
  4. 워크스페이스 API 키(프로듀서 이상)
  5. 역할
  6. 첫 세션
  7. 규칙
  8. 자주 만나는 오류
  9. 관련 문서

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

기본 URLhttps://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}/….

키 받기 #

개인 키(모든 역할) #

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

개인 키는 그 워크스페이스에서 내 역할을 가져요. 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
400validation_error본문, 쿼리, 경로 파라미터가 스키마와 맞지 않아요검증 문제 목록
400bad_request, invalid_value경로가 요청을 거부하거나, 데이터베이스가 값을 읽지 못해요(잘못된 id 등)—
400url_not_allowed웹훅이나 가져오기 URL이 공개 http(s) 주소가 아니에요—
401unauthenticated토큰이 없거나, 폐기되었거나 만료됐어요—
402out_of_credits이 테이크에 쓸 수 있는 크레딧이 부족해요needed, available(크레딧)
402plan_limit요금제에 포함되지 않아요: 무료의 파이널, 두 번째 작품, 저장 공간, 인원, 요금제 없는 팩limit(final, productions, storage, seats, packs), plan
402budget_exceeded에피소드 예산(에피소드의 budgetCredits)을 넘게 돼요episodeId, budgetCredits, spent, inFlight, needed(크레딧)
403insufficient_role내 역할이 경로의 최소 역할보다 낮아요required, actual
403not_a_signer이 팀의 컨펌 담당자가 아니에요—
403role_exceeds_caller내 역할보다 높은 역할의 초대나 키—
403not_a_person개인 키나 Claude 연결로 키를 관리하려 했어요—
404not_found행이 없거나, 볼 수 없어요—
409gate_closed게이트가 열리기 전의 파이널episode_id, waiting_on(팀, 또는 어느 에피소드에도 없는 컷은 placement)
409changed_since더 이상 현재 버전이 아닌 버전을 컨펌했어요version(현재 버전)
409already_signed_off단계가 이미 컨펌됐어요—
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/ko/api/overview.md