API
Studio, sebagai API.
REST API Filmsquare adalah API yang sama dengan yang dipakai studio dan Claude milik tiap orang, dibuka untuk skrip Anda. JSON lewat HTTPS, satu dokumen OpenAPI 3.1 yang dihasilkan dari rute-rutenya, satu bearer key per orang dan ruang kerja, serta webhook bertanda tangan untuk saat sebuah take siap.
curl -s "$FS/me" \
-H "Authorization: Bearer $FS_KEY"
WEBHOOK · POST /filmsquare/hook

S3-B5-05Seedance 2.5 · Final 1080p · 5 detik · 105,30 kredit · €5,27
BASE URL DAN AUTH
Satu key, satu peran, satu ruang kerja
Setiap panggilan mengirim Authorization: Bearer <token>: API key yang diawali fsk_, atau sesi yang sudah masuk. Rute ruang kerja membawa ruang kerja di path-nya, /v1/workspaces/{ws}/….
https://app.filmsquare.ai/v1export 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"}'ownerproducerdirectormakerreviewerviewer
Key tidak punya scope. Kekuatan sebuah key adalah perannya di satu ruang kerja, tidak pernah di atas peran orang di baliknya.
| KEY | CARANYA |
|---|---|
| Key pribadi | Settings → Claude → Use a personal key instead (pakai key pribadi). Dengan peran Anda sendiri, ditampilkan sekali. |
| Key ruang kerja | POST /workspaces/{ws}/api-keys dengan nama dan peran, oleh produser atau pemilik. Ditampilkan sekali saja; hanya hash-nya yang disimpan. |
| Cabut | POST /workspaces/{ws}/api-keys/{id}/revoke. Panggilan berikutnya dengan key itu dijawab 401 api_key_revoked. |
OPENAPI 3.1
Satu nama untuk panggilan dan tugas
GET https://app.filmsquare.ai/v1/openapi.json bersifat publik, OpenAPI 3.1, dan dihasilkan dari rute-rutenya sendiri. Setiap rute punya operationId, nama yang sama dengan yang dijalankan Claude lewat run_action, jadi panggilan yang Anda skrip dan tugas yang Anda serahkan ke Claude adalah satu hal yang sama. x-min-role menyebut peran terendah yang boleh memanggilnya. Referensi OpenAPI · MCP untuk Claude
"/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'WEBHOOK
Berlangganan, jangan polling
Produser ke atas; secret whsec_ hanya ditampilkan sekali. Jawab dengan 2xx. Pada 5xx, 429, atau timeout, Filmsquare mencoba lagi dengan exponential backoff, dari sekitar 2 detik sampai 10 menit antarpercobaan, maksimal 8 kali. x-fs-delivery tetap sama di setiap percobaan ulang. Webhook
| EVENT | DIKIRIM SAAT |
|---|---|
generation.succeeded | Sebuah take selesai dirender |
generation.failed | Sebuah render gagal |
take.selected | Sebuah take dipilih pada shot atau adegan |
asset_version.created | Sebuah render menghasilkan versi aset baru |
["*"] | Semua event |
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…KONVENSI DAN ERROR
Setiap error punya satu bentuk
| TOPIK | ATURAN |
|---|---|
| Nama field | Respons dalam snake_case, body request dalam camelCase. |
| Daftar | Daftar dijawab dengan {"items": […], "next_cursor": "…"}. Kirim cursor untuk halaman berikutnya, limit sampai 200, order asc atau desc. |
| Idempotensi | Request take menerima header Idempotency-Key: key yang sama mengembalikan take yang sama. |
| Penghapusan | Baris diarsipkan, tidak pernah dihapus. Versi, take terpilih, persetujuan, dan biaya tidak pernah berubah. |
| Tidak terlihat | Baris yang tidak boleh Anda lihat dijawab 404, sama seperti baris yang memang tidak ada. |
| STATUS | KODE | KAPAN |
|---|---|---|
| 400 | validation_error | Body, query, atau path parameter tidak cocok dengan skema |
| 401 | unauthenticated | Tanpa token, atau token yang dicabut atau kedaluwarsa |
| 402 | out_of_credits | Kredit yang tersedia tidak cukup untuk take ini |
| 402 | plan_limit | Paket tidak mencakupnya, seperti final di paket Gratis |
| 402 | budget_exceeded | Anggaran episode dalam kredit akan terlampaui |
| 403 | insufficient_role | Peran Anda di bawah x-min-role milik rute itu |
| 403 | account_blocked | Akun ditangguhkan; setiap permintaan ditolak |
| 404 | not_found | Barisnya tidak ada, atau Anda tidak boleh melihatnya |
| 409 | gate_closed | Final sebelum departemen yang ditunggunya disetujui |
| 409 | workspace_paused | Ruang kerja dijeda: tidak ada take atau alat baru yang berjalan di dalamnya |
{"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 tidak butuh key. Ia mengembalikan harga satu kredit dalam euro, harga seat dan kredit yang dibawa satu seat, akumulasi kredit, penyimpanan, dan bundel kredit: angka-angka di balik harga.
curl -s https://app.filmsquare.ai/v1/pricingPertanyaan
Apakah API-nya sama dengan yang dipakai studio?
Ya. Studio, Claude milik tiap orang, dan skrip Anda memanggil rute yang sama, dengan peran yang sama dan aturan yang sama.
Apakah API key punya scope?
Tidak. Sebuah key bekerja di satu ruang kerja dengan satu peran, tidak pernah di atas peran orang yang membuatnya. Perannya adalah cakupannya.
Di mana referensinya?
Dokumen OpenAPI 3.1 di https://app.filmsquare.ai/v1/openapi.json bersifat publik dan dihasilkan dari rute-rutenya, jadi tidak pernah tertinggal dari rute itu.
Bagaimana saya tahu sebuah take sudah siap?
Langganankan webhook ke generation.succeeded. Pengiriman ditandatangani dengan x-fs-signature dan dicoba ulang pada 5xx, 429, dan timeout.
Bisakah skrip merender final sebelum disetujui?
Tidak. Final sebelum gerbang terbuka dijawab 409 gate_closed, beserta departemen yang masih ditunggu.
Apakah harga bisa dibaca tanpa key?
Ya. GET https://app.filmsquare.ai/v1/pricing bersifat publik dan mengembalikan harga kredit, harga seat, akumulasi kredit, dan bundel kredit.