6.0 API6.1 API'ye genel bakış ve anahtarlar
API'ye genel bakış ve anahtarlar
Filmsquare REST API'si: temel URL, API anahtarı ya da oturumla kimlik doğrulama, anahtar nasıl yapılır, kurallar ve karşılaşacağın hatalar.
Stüdyonun yaptığı her şey tek bir REST API'den geçer ve sen de onu kullanabilirsin: uygulama, kendi Claude'un ve betiklerin aynı rotaları, aynı rollerle ve aynı kurallarla çağırır.
| Temel URL | https://app.filmsquare.ai/v1 |
| Biçim | HTTPS üzerinden JSON |
| Kimlik doğrulama | Authorization: Bearer <API key or session token> |
| Başvuru | https://app.filmsquare.ai/v1/openapi.json (OpenAPI 3.1, herkese açık). Bkz. OpenAPI başvurusu |
Kimlik doğrulama #
Birkaç herkese açık rota dışında her rota (GET /v1/pricing, POST /v1/signup, webhook alıcıları) bir bearer token ister:
- Bir API anahtarı,
fsk_ile başlar. Bir anahtar tek bir çalışma alanında tek bir kişiye (ya da ajan kullanıcıya) aittir ve anahtarın rolüyle hareket eder, o kişinin güncel rolünden hiçbir zaman fazlasıyla değil. - Giriş yapmış bir kişinin oturum token'ı (web uygulamasının gönderdiği).
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_… # your key
curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"
GET /me kim olduğunu, bir anahtarla gelip gelmediğini ve çalışma alanlarını döner. Her çalışma alanı rotasının yolunda
çalışma alanı id'si var: /v1/workspaces/{ws}/….
Anahtar almak #
Kişisel bir anahtar (her rol) #
- Stüdyoda, kenar çubuğunun üstündeki çalışma alanı menüsünü aç ve Settings, sonra Claude seç.
- Use a personal key instead seç, ona bir ad ver ve Create a personal key seç.
- Anahtarı kopyala. Bir kez gösterilir.
Kişisel anahtar o çalışma alanında senin kendi rolünü taşır. Claude Code için yapıldı, ama anahtar yönetmek dışında rolünün izin verdiği her API çağrısında çalışır.
Bir çalışma alanı API anahtarı (yapımcı ve üstü) #
Giriş yapmış bir yapımcı ya da sahip, API üzerinden seçtiği bir rolle anahtar yapabilir:
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"}'
Cevap tam key'i bir kez içerir; Filmsquare yalnızca hash'ini tutar. Bir anahtarın rolü hiçbir zaman seninkinin üstünde
olamaz. userId ile çalışma alanının üyesi olan bir ajan kullanıcı için anahtar yapabilirsin.
GET /workspaces/{ws}/api-keys anahtarları listeler (yalnızca ön ek); POST /workspaces/{ws}/api-keys/{id}/revoke birini
iptal eder. Anahtarlar anahtar yapamaz: bu rotalar giriş yapmış bir kişi ya da bir çalışma alanı anahtarı ister ve kişisel
bir anahtarı ya da bir Claude bağlantısını 403 not_a_person ile reddeder.
Roller #
Her rotanın bir en düşük rolü var: owner > producer > director > maker > reviewer > viewer. Bunun altındaki bir
çağrı {"required": "director", "actual": "maker"} ile 403 insufficient_role alır. Görmene izin olmayan bir satır, var
olmayan bir satırla aynı şekilde 404 cevaplar. Bkz. Ekip, roller ve erişim.
İlk oturum #
# 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 keyframe, video, dialogue, sfx ya da music'tir; tier draft ya da final'dir. Bağlı hiçbir model henüz
sfx ya da music yapmaz: o çekimler yükleme olarak gelir (createUploadTicket, sonra hedef katmanla completeUpload).
modelKey'i boş bırakırsan Filmsquare onaylanan çekim başına en düşük maliyetli yapabilen modele yönlendirir. Yoklama
yerine webhook'lara abone ol.
Kurallar #
| Konu | Kural |
|---|---|
| Alan adları | Yanıtlar snake_case, istek gövdeleri camelCase |
| Listeler | {"items": […], "next_cursor": "…"}. Sonraki sayfa için cursor ver; limit en fazla 200; order asc ya da desc |
| Arşivlenmiş satırlar | includeArchived=true olmadıkça listelerin dışında kalır |
| Silmek | Satırlar silinmez, arşivlenir (POST …/{id}/archive). Versiyonlar, seçimler, onaylar ve maliyetler hiç değişmez |
| İdempotency | Üretim istekleri bir Idempotency-Key başlığı (ya da gövdede idempotencyKey) alır: aynı anahtar var olan üretimi döner |
| Para | Maliyetler kredi cinsindendir, her biri işin başladığı orandan; bir kredinin euro olarak neye mal olduğu GET /v1/pricing ve Krediler ve maliyetler içinde |
Karşılaşacağın hatalar #
Her hata aynı biçimdedir:
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
"details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
| Durum | Kod | Ne zaman | details |
|---|---|---|---|
| 400 | validation_error | Gövde, sorgu ya da bir yol parametresi şemaya uymuyor | Doğrulama sorunlarının listesi |
| 400 | bad_request, invalid_value | Rota isteği reddediyor ya da veritabanı bir değeri okuyamıyor (bozuk bir id gibi) | — |
| 400 | url_not_allowed | Bir webhook ya da içe aktarma URL'si herkese açık bir http(s) adresi değil | — |
| 401 | unauthenticated | Token yok ya da iptal edilmiş ya da süresi dolmuş | — |
| 402 | out_of_credits | Bu çekim için harcanabilir yeterli kredi yok | needed, available (kredi) |
| 402 | plan_limit | Abonelik bunu içermiyor: Free'de bir final, ikinci bir yapım, depolama alanı, kişiler, abonelik olmadan paketler | limit (final, productions, storage, seats, packs), plan |
| 402 | budget_exceeded | Bölümün bütçesi (bölümdeki budgetCredits) aşılacak | episodeId, budgetCredits, spent, inFlight, needed (kredi) |
| 403 | insufficient_role | Rolün rotanın en düşüğünün altında | required, actual |
| 403 | not_a_signer | Bu departmanın onaylayanı değilsin | — |
| 403 | role_exceeds_caller | Kendi rolünün üstünde bir rolle davet ya da anahtar | — |
| 403 | not_a_person | Kişisel bir anahtar ya da bir Claude bağlantısıyla anahtar yönetmek | — |
| 404 | not_found | Satır yok, ya da görmene izin yok | — |
| 409 | gate_closed | Kapı açılmadan bir final | episode_id, waiting_on (departmanlar, ya da hiçbir bölümde olmayan bir plan için placement) |
| 409 | changed_since | Artık güncel olmayan bir versiyonu onayladın | version (güncel olan) |
| 409 | already_signed_off | Adım zaten onaylanmış | — |
| 409 | element_version_frozen | Bir çekimin zaten kullandığı bir versiyona referans eklendi | — |
| 409 | conflict | Bu değerlerle bir satır zaten var | — |
| 422 | foreign_key_violation, check_violation, not_null_violation | Başvurulan bir satır yok (ya da başka bir çalışma alanında), ya da bir veritabanı kuralı değerleri reddetti | constraint, table, detail |
402 out_of_credits şöyle görünür:
{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
"details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}
İlgili #
- Webhook'lar
- OpenAPI başvurusu
- Claude neler yapabilir: aynı API, MCP üzerinden