Filmsquare

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"
Kirim permintaanGET /v1/me

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}/….

BASE URL
https://app.filmsquare.ai/v1
PANGGILAN PERTAMA
export 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"}'
  1. owner
  2. producer
  3. director
  4. maker
  5. reviewer
  6. viewer

Key tidak punya scope. Kekuatan sebuah key adalah perannya di satu ruang kerja, tidak pernah di atas peran orang di baliknya.

KEYCARANYA
Key pribadiSettings → Claude → Use a personal key instead (pakai key pribadi). Dengan peran Anda sendiri, ditampilkan sekali.
Key ruang kerjaPOST /workspaces/{ws}/api-keys dengan nama dan peran, oleh produser atau pemilik. Ditampilkan sekali saja; hanya hash-nya yang disimpan.
CabutPOST /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

SATU OPERASI
"/workspaces/{ws}/shots/{id}/generations": {
  "post": {
    "operationId": "generateForShot",
    "x-min-role": "maker",
    …
  }
}
TERMINAL
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

EVENTDIKIRIM SAAT
generation.succeededSebuah take selesai dirender
generation.failedSebuah render gagal
take.selectedSebuah take dipilih pada shot atau adegan
asset_version.createdSebuah render menghasilkan versi aset baru
["*"]Semua event
BERLANGGANAN
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"]}'
SATU PENGIRIMAN
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

TOPIKATURAN
Nama fieldRespons dalam snake_case, body request dalam camelCase.
DaftarDaftar dijawab dengan {"items": […], "next_cursor": "…"}. Kirim cursor untuk halaman berikutnya, limit sampai 200, order asc atau desc.
IdempotensiRequest take menerima header Idempotency-Key: key yang sama mengembalikan take yang sama.
PenghapusanBaris diarsipkan, tidak pernah dihapus. Versi, take terpilih, persetujuan, dan biaya tidak pernah berubah.
Tidak terlihatBaris yang tidak boleh Anda lihat dijawab 404, sama seperti baris yang memang tidak ada.
STATUSKODEKAPAN
400validation_errorBody, query, atau path parameter tidak cocok dengan skema
401unauthenticatedTanpa token, atau token yang dicabut atau kedaluwarsa
402out_of_creditsKredit yang tersedia tidak cukup untuk take ini
402plan_limitPaket tidak mencakupnya, seperti final di paket Gratis
402budget_exceededAnggaran episode dalam kredit akan terlampaui
403insufficient_rolePeran Anda di bawah x-min-role milik rute itu
403account_blockedAkun ditangguhkan; setiap permintaan ditolak
404not_foundBarisnya tidak ada, atau Anda tidak boleh melihatnya
409gate_closedFinal sebelum departemen yang ditunggunya disetujui
409workspace_pausedRuang kerja dijeda: tidak ada take atau alat baru yang berjalan di dalamnya
SETIAP ERROR PUNYA SATU BENTUK
{"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.

TERMINAL
curl -s https://app.filmsquare.ai/v1/pricing

Pertanyaan

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.