Filmsquare YardımDokümanlar

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.

Güncellendi 4 dk okuma.md

Bu sayfada
  1. Kimlik doğrulama
  2. Anahtar almak
  3. Kişisel bir anahtar (her rol)
  4. Bir çalışma alanı API anahtarı (yapımcı ve üstü)
  5. Roller
  6. İlk oturum
  7. Kurallar
  8. Karşılaşacağın hatalar
  9. İlgili

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 URLhttps://app.filmsquare.ai/v1
BiçimHTTPS üzerinden JSON
Kimlik doğrulamaAuthorization: Bearer <API key or session token>
Başvuruhttps://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) #

  1. Stüdyoda, kenar çubuğunun üstündeki çalışma alanı menüsünü aç ve Settings, sonra Claude seç.
  2. Use a personal key instead seç, ona bir ad ver ve Create a personal key seç.
  3. 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 #

KonuKural
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ırlarincludeArchived=true olmadıkça listelerin dışında kalır
SilmekSatı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
ParaMaliyetler 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"]}}}
DurumKodNe zamandetails
400validation_errorGövde, sorgu ya da bir yol parametresi şemaya uymuyorDoğrulama sorunlarının listesi
400bad_request, invalid_valueRota isteği reddediyor ya da veritabanı bir değeri okuyamıyor (bozuk bir id gibi)—
400url_not_allowedBir webhook ya da içe aktarma URL'si herkese açık bir http(s) adresi değil—
401unauthenticatedToken yok ya da iptal edilmiş ya da süresi dolmuş—
402out_of_creditsBu çekim için harcanabilir yeterli kredi yokneeded, available (kredi)
402plan_limitAbonelik bunu içermiyor: Free'de bir final, ikinci bir yapım, depolama alanı, kişiler, abonelik olmadan paketlerlimit (final, productions, storage, seats, packs), plan
402budget_exceededBölümün bütçesi (bölümdeki budgetCredits) aşılacakepisodeId, budgetCredits, spent, inFlight, needed (kredi)
403insufficient_roleRolün rotanın en düşüğünün altındarequired, actual
403not_a_signerBu departmanın onaylayanı değilsin—
403role_exceeds_callerKendi rolünün üstünde bir rolle davet ya da anahtar—
403not_a_personKişisel bir anahtar ya da bir Claude bağlantısıyla anahtar yönetmek—
404not_foundSatır yok, ya da görmene izin yok—
409gate_closedKapı açılmadan bir finalepisode_id, waiting_on (departmanlar, ya da hiçbir bölümde olmayan bir plan için placement)
409changed_sinceArtık güncel olmayan bir versiyonu onayladınversion (güncel olan)
409already_signed_offAdım zaten onaylanmış—
409element_version_frozenBir çekimin zaten kullandığı bir versiyona referans eklendi—
409conflictBu değerlerle bir satır zaten var—
422foreign_key_violation, check_violation, not_null_violationBaşvurulan bir satır yok (ya da başka bir çalışma alanında), ya da bir veritabanı kuralı değerleri reddetticonstraint, 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}}}

Bu sayfa Markdown olarak: /docs/tr/api/overview.md