6.0 API6.3 OpenAPI 레퍼런스
OpenAPI 레퍼런스
Filmsquare OpenAPI 3.1 문서가 어디 있는지, 어떻게 읽는지(operation id, x-min-role, 태그), 영역별 API 지도를 알려 드려요.
API의 전체 레퍼런스는 경로 자체에서 생성한 OpenAPI 3.1 문서 하나라서 항상 최신이에요.
https://app.filmsquare.ai/v1/openapi.json
공개 문서라서 토큰이 필요 없어요.
curl -s https://app.filmsquare.ai/v1/openapi.json | jq '.paths | keys | length'
문서 읽는 법 #
| 필드 | 뜻 |
|---|---|
paths | /v1로 시작하는 전체 경로. 호스트 https://app.filmsquare.ai와 함께 써요 |
operationId | 경로마다 고정된 이름. 예: generateForShot. 같은 이름이 내 Claude가 run_action으로 실행하는 action이에요 |
summary | 경로가 하는 일을 한 줄로. find_actions가 검색하는 대상이기도 해요 |
x-min-role | 호출할 수 있는 가장 낮은 워크스페이스 역할: viewer … owner, authenticated(워크스페이스 없는, 로그인한 모든 호출자), public |
security | bearerAuth(API 키 fsk_… 또는 세션 토큰), 공개 경로는 비어 있어요 |
tags | API의 영역. 예: shots, takes, elements, credits |
| 오류 응답 | 모든 경로가 공통 Error 스키마를 나열해요: {"error": {"code", "message", "details"}} |
OpenAPI 툴(Postman, Insomnia, Bruno)에서 가져오거나, openapi-typescript 같은 걸로 타입이 있는 클라이언트를 생성할 수 있어요.
영역별 API #
| 영역 | 예시(operationId) |
|---|---|
| 계정과 워크스페이스 | getMe, listWorkspaces, createWorkspace, listMembers, createInvitation, setMemberScope |
| 작품과 구조 | listProjects, createProject, createEpisode, createScene, createShot, addShotToEpisode, getEpisodeStructure |
| 시나리오와 브레이크다운 | importScript, createScriptRevision, submitBreakdown, getEpisodeScript, listScriptRevisions |
| 시나리오 태그 | listScriptTags, autoTagScript, createScriptTag, updateScriptTag, archiveScriptTag, createElementFromScriptTag |
| 팀과 컨펌 | listProductionSteps, updateProductionStep, addProductionStep, getEpisodeSteps, requestSignoff, decideSignoff, listWaitingOnMe, getAnimaticReel |
| 테이크와 생성 | estimateShotGeneration, generateForShot, generateForScene, promoteGeneration, rerollTake, retryGeneration, cancelGeneration, listGenerations, getGeneration, selectTake, listTools, estimateTool, applyTool |
| 요소 | createElement, createQuickElement, forkElementVersion, generateForElement, acceptElementTake, searchHandles |
| 의상 룩 | listEpisodeLooks, createElementLook, updateElementLook, archiveElementLook, setLookScene |
| 3D 동선 | getEpisodeBlocking, pushBlockingFrame, pushBlockingFrames, listPrevisClips, addPrevisClips, countPrevisClip, archivePrevisClip, moveTake, moveAsset, findShotByCode, setShotExternalCodes, estimateBlockingStill, makeBlockingStill |
| 파일 | createUploadTicket, startMultipartUpload, signUploadPart, completeMultipartUpload, abortMultipartUpload, getMultipartUpload, completeUpload, importFromUrls, getAssetVersionUrl, getAssetVersionLineage, exportEpisodeManifest |
| 리뷰 | listThreads, createThread, addThreadMessage, carryThreadForward, getInbox, markInboxRead, getActivity |
| 편집 버전 | listEdits, createEdit, getEdit, addEditVersion |
| 편집본 | getEpisodeCut, setCutClipTrim, reorderEpisodeCut, reviseTake, createCutExport, listCutExports |
| 연결과 라우팅 | getContinuitySheet, scanContinuity, recordContinuityCheck, getModelAcceptance |
| 폴더와 캔버스 | listFolders, createFolder, addFolderItems, getCanvas, applyCanvasOps, runCanvasNode |
| 브리프와 작업자 | createBrief, offerAssignment, submitDelivery, markAssignmentPaid, getMakersOverview |
| 비용과 크레딧 | getEpisodeCosts, getCredits, listCreditEntries, getPricing, getPlan, listInvoices |
| 연동 | createApiKey, revokeApiKey, createWebhook, updateWebhook, deleteWebhook |
GET /v1/pricing(getPricing)은 공개예요. 크레딧 가격, 요금제, 팩을 실시간으로 보여 줘요.
문서에 없는 것 #
- MCP 엔드포인트
POST /v1/mcp. Claude 연결을 보세요. - Claude 연결용 OAuth 엔드포인트(
/oauth/*,/.well-known/oauth-*). - 캔버스와 접속 표시용 실시간 소켓(
/v1/realtime/…).createCanvasSession이나createProjectPresenceSession이 주는 단기 티켓으로 열려요.
말로 검색하기 #
find_actions는 같은 카탈로그를 현장 용어(“pick take”, “notes”, “render”)로 검색해요. 문서를 읽지 않고도 내 Claude에서 쓸 수 있어요. Claude가 할 수 있는 일을 보세요.
관련 문서 #
Claude와 함께
MCP내 Claude가 MCP로 이 일을 해요. 내 이름으로, 내 역할대로요:
find_actionsAPI로 할 수 있는 모든 일을 검색해서, 맞는 액션을 입력값과 함께 돌려줘요.
이렇게 요청해요: 단계의 컨펌 규칙을 바꾸는 액션을 찾아 줘.
Claude 연결 5.1