6.0 API6.1 Ikhtisar API dan kunci
Ikhtisar API dan kunci
REST API Filmsquare: base URL, autentikasi dengan kunci API atau sesi, cara membuat kunci, konvensi, dan error yang akan Anda temui.
Semua yang dilakukan studio lewat satu REST API, dan Anda juga bisa memakainya: aplikasi, Claude Anda sendiri, dan skrip Anda memanggil rute yang sama, dengan peran dan aturan yang sama.
| Base URL | https://app.filmsquare.ai/v1 |
| Format | JSON lewat HTTPS |
| Autentikasi | Authorization: Bearer <API key or session token> |
| Referensi | https://app.filmsquare.ai/v1/openapi.json (OpenAPI 3.1, publik). Lihat Referensi OpenAPI |
Autentikasi #
Setiap rute kecuali beberapa yang publik (GET /v1/pricing, POST /v1/signup, penerima webhook) butuh bearer
token:
- Kunci API, dimulai dengan
fsk_. Kunci milik satu orang (atau pengguna agen) di satu ruang kerja, dan bertindak dengan peran kunci itu, tidak pernah lebih dari peran orang itu saat ini. - Token sesi orang yang sudah masuk (yang dikirim aplikasi web).
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_… # your key
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
GET /me mengembalikan siapa Anda, apakah Anda masuk dengan kunci, dan ruang kerja Anda. Setiap rute ruang kerja memuat
id ruang kerja di path-nya: /v1/workspaces/{ws}/….
Mendapatkan kunci #
Kunci pribadi (peran apa pun) #
- Di studio, buka menu ruang kerja di bagian atas sidebar dan pilih Settings, lalu Claude.
- Pilih Use a personal key instead, beri nama, dan pilih Create a personal key.
- Salin kuncinya. Kunci hanya ditampilkan sekali.
Kunci pribadi memegang peran Anda sendiri di ruang kerja itu. Dibuat untuk Claude Code, tetapi bisa dipakai untuk panggilan API apa pun yang diizinkan peran Anda, kecuali mengelola kunci.
Kunci API ruang kerja (produser ke atas) #
Produser atau pemilik yang sudah masuk bisa membuat kunci dengan peran pilihan lewat 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"}'
Jawabannya memuat key lengkap sekali saja; Filmsquare hanya menyimpan hash-nya. Peran kunci tidak pernah bisa di atas peran Anda. Dengan
userId Anda bisa membuat kunci untuk pengguna agen yang menjadi anggota ruang kerja.
GET /workspaces/{ws}/api-keys mendaftar kunci (hanya prefiks); POST /workspaces/{ws}/api-keys/{id}/revoke mencabut satu.
Kunci tidak bisa membuat kunci: rute ini butuh orang yang sudah masuk atau kunci ruang kerja, dan menolak kunci pribadi atau
koneksi Claude dengan 403 not_a_person.
Peran #
Setiap rute punya peran minimum: owner > producer > director > maker > reviewer > viewer. Panggilan di bawahnya
mendapat 403 insufficient_role dengan {"required": "director", "actual": "maker"}. Baris yang tidak boleh Anda lihat dijawab 404,
sama seperti baris yang tidak ada. Lihat Kru, peran, dan akses.
Sesi pertama #
# 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 adalah keyframe, video, dialogue, sfx, atau music; tier adalah draft atau final. Belum ada model terhubung yang
membuat sfx atau music: take itu masuk sebagai unggahan (createUploadTicket, lalu completeUpload dengan
layer target). Kalau modelKey tidak diisi,
Filmsquare mengarahkan ke model yang mampu dengan biaya terendah per take yang disetujui. Daripada polling, berlanggananlah ke
webhook.
Konvensi #
| Topik | Aturan |
|---|---|
| Nama field | Respons dalam snake_case, body permintaan dalam camelCase |
| Daftar | {"items": […], "next_cursor": "…"}. Kirim cursor untuk halaman berikutnya; limit hingga 200; order asc atau desc |
| Baris yang diarsipkan | Tidak disertakan di daftar kecuali includeArchived=true |
| Menghapus | Baris diarsipkan (POST …/{id}/archive), tidak dihapus. Versi, pilihan, persetujuan, dan biaya tidak pernah diubah |
| Idempotensi | Permintaan generate menerima header Idempotency-Key (atau idempotencyKey di body): kunci yang sama mengembalikan generate yang sudah ada |
| Uang | Biaya dalam kredit, masing-masing dengan tarif saat pekerjaan dimulai; harga kredit dalam euro ada di GET /v1/pricing dan Kredit dan biaya |
Error yang akan Anda temui #
Setiap error punya bentuk yang sama:
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
| Status | Kode | Kapan | details |
|---|---|---|---|
| 400 | validation_error | Body, query, atau parameter path tidak cocok dengan skema | Daftar masalah validasi |
| 400 | bad_request, invalid_value | Rute menolak permintaan, atau database tidak bisa membaca sebuah nilai (seperti id yang salah bentuk) | — |
| 400 | url_not_allowed | URL webhook atau impor bukan alamat http(s) publik | — |
| 401 | unauthenticated | Tidak ada token, atau token yang dicabut atau kedaluwarsa | — |
| 402 | out_of_credits | Kredit yang bebas dipakai tidak cukup untuk take ini | needed, available (kredit) |
| 402 | plan_limit | Paket tidak mencakup ini: final di Free, produksi kedua, penyimpanan, seat, bundel tanpa paket | limit (final, productions, storage, seats, packs), plan |
| 402 | budget_exceeded | Anggaran episode (budgetCredits pada episode) akan terlampaui | episodeId, budgetCredits, spent, inFlight, needed (kredit) |
| 403 | insufficient_role | Peran Anda di bawah minimum rute | required, actual |
| 403 | not_a_signer | Anda bukan penyetuju departemen ini | — |
| 403 | role_exceeds_caller | Undangan atau kunci dengan peran di atas peran Anda sendiri | — |
| 403 | not_a_person | Mengelola kunci dengan kunci pribadi atau koneksi Claude | — |
| 404 | not_found | Baris tidak ada, atau tidak boleh Anda lihat | — |
| 409 | gate_closed | Final sebelum gerbang terbuka | episode_id, waiting_on (departemen, atau placement untuk shot yang tidak ada di episode mana pun) |
| 409 | changed_since | Anda menyetujui versi yang bukan lagi yang terkini | version (yang terkini) |
| 409 | already_signed_off | Tahap sudah disetujui | — |
| 409 | element_version_frozen | Referensi ditambahkan ke versi yang sudah dipakai sebuah take | — |
| 409 | conflict | Baris dengan nilai ini sudah ada | — |
| 422 | foreign_key_violation, check_violation, not_null_violation | Baris yang dirujuk tidak ada (atau ada di ruang kerja lain), atau aturan database menolak nilainya | constraint, table, detail |
402 out_of_credits tampak seperti ini:
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
"details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
Terkait #
- Webhook
- Referensi OpenAPI
- Apa yang bisa dikerjakan Claude: API yang sama lewat MCP