Filmsquare

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"
İstek gönderGET /v1/me

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

TEMEL URL
https://app.filmsquare.ai/v1
İLK ÇAĞRILAR
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

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.

ANAHTARNASIL
Kişisel anahtarSettings → 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 etPOST /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

TEK İŞLEM
"/workspaces/{ws}/shots/{id}/generations": {
  "post": {
    "operationId": "generateForShot",
    "x-min-role": "maker",
    …
  }
}
TERMİNAL
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

OLAYNE ZAMAN GÖNDERİLİR
generation.succeededBir çekimin render'ı bitti
generation.failedBir render başarısız oldu
take.selectedBir planda ya da sahnede çekim seçildi
asset_version.createdBir render yeni bir asset versiyonu üretti
["*"]Tüm olaylar
ABONE OL
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"]}'
BİR TESLİMAT
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

KONUKURAL
Alan adlarıYanıtlar snake_case, istek gövdeleri camelCase.
ListelerListeler {"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.
SilmeSatırlar arşivlenir, asla silinmez. Versiyonlar, seçilen çekimler, onaylar ve maliyetler asla değişmez.
GörünmüyorGöremeyeceğin bir satır, hiç var olmayan bir satırla aynı şekilde 404 yanıtı verir.
DURUMKODNE ZAMAN
400validation_errorGövde, sorgu ya da bir yol parametresi şemayla uyuşmuyor
401unauthenticatedToken yok ya da iptal edilmiş veya süresi dolmuş
402out_of_creditsBu çekim için yeterli boş kredi yok
402plan_limitAbonelik bunu içermiyor; ör. Ücretsiz abonelikte final
402budget_exceededBölümün kredi bütçesi aşılacak
403insufficient_roleRolün, rotanın x-min-role değerinin altında
403account_blockedHesap askıya alındı; her istek reddediliyor
404not_foundSatır yok ya da onu göremezsin
409gate_closedBeklediği departmanlar onaylamadan istenen bir final
409workspace_pausedÇalışma alanı duraklatıldı: içinde yeni bir çekim ya da araç başlamaz
HER HATANIN TEK BİR ŞEKLİ VAR
{"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.

TERMİNAL
curl -s https://app.filmsquare.ai/v1/pricing

Sorular

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.