API
Stüdyo, bir API olarak.
Filmsquare'in REST API'si, stüdyonun ve kişinin kendi Claude'unun kullandığı API'nin aynısıdır; senin script'lerine açık. HTTPS üzerinden JSON, rotalardan üretilmiş tek bir OpenAPI 3.1 dokümanı, kişi ve çalışma alanı başına bearer anahtar ve bir çekim hazır olunca imzalı webhook'lar.
curl -s "$FS/me" \
-H "Authorization: Bearer $FS_KEY"
WEBHOOK · POST /filmsquare/hook

S3-B5-05Seedance 2.5 · Final 1080p · 5 sn · 105,30 kredi · €5,27
TEMEL URL VE YETKİLENDİRME
Bir anahtar, bir rol, bir çalışma alanı
Her çağrı Authorization: Bearer <token> gönderir: fsk_ ile başlayan bir API anahtarı ya da oturum açılmış bir oturum. Çalışma alanı rotaları çalışma alanını yolda taşır: /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
Anahtarların kapsamı yoktur. Bir anahtarın gücü, tek bir çalışma alanındaki rolüdür; arkasındaki kişinin rolünün üstüne asla çıkmaz.
| ANAHTAR | NASIL |
|---|---|
| Kişisel anahtar | Settings → Claude → Use a personal key instead. Kendi rolün, bir kez gösterilir. |
| Çalışma alanı anahtarı | POST /workspaces/{ws}/api-keys, bir yapımcı ya da sahip tarafından bir ad ve bir rolle oluşturulur. Bir kez gösterilir; yalnızca hash'i saklanır. |
| İptal et | POST /workspaces/{ws}/api-keys/{id}/revoke. Onunla yapılan sonraki çağrı 401 api_key_revoked yanıtı verir. |
OPENAPI 3.1
Bir çağrı ve bir iş için tek ad
GET https://app.filmsquare.ai/v1/openapi.json herkese açıktır, OpenAPI 3.1'dir ve rotaların kendisinden üretilir. Her rotanın bir operationId'i vardır; Claude'un run_action ile çalıştırdığı adın aynısı. Yani script'lediğin bir çağrı ile Claude'a verdiğin bir iş aynı şeydir. x-min-role, çağırabilecek en düşük rolü söyler. OpenAPI referansı · Claude için MCP
"/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'LAR
Sormak yerine abone ol
Yapımcı ve üstü; whsec_ secret'ı bir kez gösterilir. 2xx ile yanıtla. 5xx, 429 ya da zaman aşımında Filmsquare üstel geri çekilmeyle yeniden dener: denemeler arasında yaklaşık 2 saniyeden 10 dakikaya kadar, en fazla 8 deneme. x-fs-delivery denemeler boyunca aynı kalır. Webhook'lar
| OLAY | NE ZAMAN GÖNDERİLİR |
|---|---|
generation.succeeded | Bir çekimin render'ı bitti |
generation.failed | Bir render başarısız oldu |
take.selected | Bir planda ya da sahnede çekim seçildi |
asset_version.created | Bir render yeni bir asset versiyonu üretti |
["*"] | Tüm olaylar |
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…KURALLAR VE HATALAR
Her hatanın tek bir şekli var
| KONU | KURAL |
|---|---|
| Alan adları | Yanıtlar snake_case, istek gövdeleri camelCase. |
| Listeler | Listeler {"items": […], "next_cursor": "…"} yanıtı verir. Sonraki sayfa için cursor, en fazla 200 olmak üzere limit, sıralama için asc ya da desc geçir. |
| Idempotency | Çekim istekleri bir Idempotency-Key başlığı kabul eder: aynı anahtar aynı çekimi döner. |
| Silme | Satırlar arşivlenir, asla silinmez. Versiyonlar, seçilen çekimler, onaylar ve maliyetler asla değişmez. |
| Görünmüyor | Göremeyeceğin bir satır, hiç var olmayan bir satırla aynı şekilde 404 yanıtı verir. |
| DURUM | KOD | NE ZAMAN |
|---|---|---|
| 400 | validation_error | Gövde, sorgu ya da bir yol parametresi şemayla uyuşmuyor |
| 401 | unauthenticated | Token yok ya da iptal edilmiş veya süresi dolmuş |
| 402 | out_of_credits | Bu çekim için yeterli boş kredi yok |
| 402 | plan_limit | Abonelik bunu içermiyor; ör. Ücretsiz abonelikte final |
| 402 | budget_exceeded | Bölümün kredi bütçesi aşılacak |
| 403 | insufficient_role | Rolün, rotanın x-min-role değerinin altında |
| 403 | account_blocked | Hesap askıya alındı; her istek reddediliyor |
| 404 | not_found | Satır yok ya da onu göremezsin |
| 409 | gate_closed | Beklediği departmanlar onaylamadan istenen bir final |
| 409 | workspace_paused | Çalışma alanı duraklatıldı: içinde yeni bir çekim ya da araç başlamaz |
{"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 anahtar gerektirmez. Bir kredinin euro fiyatını, kişi başı fiyatları ve kişi başına gelen kredileri, devreden krediyi, depolamayı ve kredi paketlerini döner: fiyatların arkasındaki rakamlar.
curl -s https://app.filmsquare.ai/v1/pricingSorular
API, stüdyonun kullandığıyla aynı mı?
Evet. Stüdyo, kişinin kendi Claude'u ve senin script'lerin aynı rotaları çağırır; aynı roller ve aynı kurallarla.
API anahtarlarının kapsamı var mı?
Hayır. Bir anahtar tek bir çalışma alanında tek bir rolle çalışır; onu oluşturan kişinin rolünün üstüne asla çıkmaz. Kapsam rolün kendisidir.
Referans nerede?
https://app.filmsquare.ai/v1/openapi.json adresindeki OpenAPI 3.1 dokümanı herkese açıktır ve rotalardan üretilir; bu yüzden rotaların gerisinde kalmaz.
Bir çekimin hazır olduğunu nasıl anlarım?
Bir webhook'u generation.succeeded olayına abone et. Teslimatlar x-fs-signature ile imzalanır; 5xx, 429 ve zaman aşımlarında yeniden denenir.
Bir script onaydan önce final render alabilir mi?
Hayır. Kapı açılmadan istenen final, beklediği departmanlarla birlikte 409 gate_closed yanıtı verir.
Fiyatlar anahtarsız okunabilir mi?
Evet. GET https://app.filmsquare.ai/v1/pricing herkese açıktır; kredi fiyatını, kişi başı fiyatları, devreden krediyi ve paketleri döner.