Filmsquare BantuanPanduan

6.0 API6.1 Ikhtisar API dan kunci

Ikhtisar API dan kunci

REST API Filmsquare: base URL, autentikasi dengan kunci API atau sesi, cara membuat kunci, konvensi, dan error yang akan Anda temui.

Diperbarui 5 menit baca.md

Di halaman ini
  1. Autentikasi
  2. Mendapatkan kunci
  3. Kunci pribadi (peran apa pun)
  4. Kunci API ruang kerja (produser ke atas)
  5. Peran
  6. Sesi pertama
  7. Konvensi
  8. Error yang akan Anda temui
  9. Terkait

Semua yang dilakukan studio lewat satu REST API, dan Anda juga bisa memakainya: aplikasi, Claude Anda sendiri, dan skrip Anda memanggil rute yang sama, dengan peran dan aturan yang sama.

Base URLhttps://app.filmsquare.ai/v1
FormatJSON lewat HTTPS
AutentikasiAuthorization: Bearer <API key or session token>
Referensihttps://app.filmsquare.ai/v1/openapi.json (OpenAPI 3.1, publik). Lihat Referensi OpenAPI

Autentikasi #

Setiap rute kecuali beberapa yang publik (GET /v1/pricing, POST /v1/signup, penerima webhook) butuh bearer token:

  • Kunci API, dimulai dengan fsk_. Kunci milik satu orang (atau pengguna agen) di satu ruang kerja, dan bertindak dengan peran kunci itu, tidak pernah lebih dari peran orang itu saat ini.
  • Token sesi orang yang sudah masuk (yang dikirim aplikasi web).
export FS=https://app.filmsquare.ai/v1
export FS_KEY=fsk_…   # your key

curl -s "$FS/me" -H "Authorization: Bearer $FS_KEY"

GET /me mengembalikan siapa Anda, apakah Anda masuk dengan kunci, dan ruang kerja Anda. Setiap rute ruang kerja memuat id ruang kerja di path-nya: /v1/workspaces/{ws}/….

Mendapatkan kunci #

Kunci pribadi (peran apa pun) #

  1. Di studio, buka menu ruang kerja di bagian atas sidebar dan pilih Settings, lalu Claude.
  2. Pilih Use a personal key instead, beri nama, dan pilih Create a personal key.
  3. Salin kuncinya. Kunci hanya ditampilkan sekali.

Kunci pribadi memegang peran Anda sendiri di ruang kerja itu. Dibuat untuk Claude Code, tetapi bisa dipakai untuk panggilan API apa pun yang diizinkan peran Anda, kecuali mengelola kunci.

Kunci API ruang kerja (produser ke atas) #

Produser atau pemilik yang sudah masuk bisa membuat kunci dengan peran pilihan lewat API:

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"}'

Jawabannya memuat key lengkap sekali saja; Filmsquare hanya menyimpan hash-nya. Peran kunci tidak pernah bisa di atas peran Anda. Dengan userId Anda bisa membuat kunci untuk pengguna agen yang menjadi anggota ruang kerja.

GET /workspaces/{ws}/api-keys mendaftar kunci (hanya prefiks); POST /workspaces/{ws}/api-keys/{id}/revoke mencabut satu. Kunci tidak bisa membuat kunci: rute ini butuh orang yang sudah masuk atau kunci ruang kerja, dan menolak kunci pribadi atau koneksi Claude dengan 403 not_a_person.

Peran #

Setiap rute punya peran minimum: owner > producer > director > maker > reviewer > viewer. Panggilan di bawahnya mendapat 403 insufficient_role dengan {"required": "director", "actual": "maker"}. Baris yang tidak boleh Anda lihat dijawab 404, sama seperti baris yang tidak ada. Lihat Kru, peran, dan akses.

Sesi pertama #

# 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 adalah keyframe, video, dialogue, sfx, atau music; tier adalah draft atau final. Belum ada model terhubung yang membuat sfx atau music: take itu masuk sebagai unggahan (createUploadTicket, lalu completeUpload dengan layer target). Kalau modelKey tidak diisi, Filmsquare mengarahkan ke model yang mampu dengan biaya terendah per take yang disetujui. Daripada polling, berlanggananlah ke webhook.

Konvensi #

TopikAturan
Nama fieldRespons dalam snake_case, body permintaan dalam camelCase
Daftar{"items": […], "next_cursor": "…"}. Kirim cursor untuk halaman berikutnya; limit hingga 200; order asc atau desc
Baris yang diarsipkanTidak disertakan di daftar kecuali includeArchived=true
MenghapusBaris diarsipkan (POST …/{id}/archive), tidak dihapus. Versi, pilihan, persetujuan, dan biaya tidak pernah diubah
IdempotensiPermintaan generate menerima header Idempotency-Key (atau idempotencyKey di body): kunci yang sama mengembalikan generate yang sudah ada
UangBiaya dalam kredit, masing-masing dengan tarif saat pekerjaan dimulai; harga kredit dalam euro ada di GET /v1/pricing dan Kredit dan biaya

Error yang akan Anda temui #

Setiap error punya bentuk yang sama:

{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
  "details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
StatusKodeKapandetails
400validation_errorBody, query, atau parameter path tidak cocok dengan skemaDaftar masalah validasi
400bad_request, invalid_valueRute menolak permintaan, atau database tidak bisa membaca sebuah nilai (seperti id yang salah bentuk)—
400url_not_allowedURL webhook atau impor bukan alamat http(s) publik—
401unauthenticatedTidak ada token, atau token yang dicabut atau kedaluwarsa—
402out_of_creditsKredit yang bebas dipakai tidak cukup untuk take inineeded, available (kredit)
402plan_limitPaket tidak mencakup ini: final di Free, produksi kedua, penyimpanan, seat, bundel tanpa paketlimit (final, productions, storage, seats, packs), plan
402budget_exceededAnggaran episode (budgetCredits pada episode) akan terlampauiepisodeId, budgetCredits, spent, inFlight, needed (kredit)
403insufficient_rolePeran Anda di bawah minimum ruterequired, actual
403not_a_signerAnda bukan penyetuju departemen ini—
403role_exceeds_callerUndangan atau kunci dengan peran di atas peran Anda sendiri—
403not_a_personMengelola kunci dengan kunci pribadi atau koneksi Claude—
404not_foundBaris tidak ada, atau tidak boleh Anda lihat—
409gate_closedFinal sebelum gerbang terbukaepisode_id, waiting_on (departemen, atau placement untuk shot yang tidak ada di episode mana pun)
409changed_sinceAnda menyetujui versi yang bukan lagi yang terkiniversion (yang terkini)
409already_signed_offTahap sudah disetujui—
409element_version_frozenReferensi ditambahkan ke versi yang sudah dipakai sebuah take—
409conflictBaris dengan nilai ini sudah ada—
422foreign_key_violation, check_violation, not_null_violationBaris yang dirujuk tidak ada (atau ada di ruang kerja lain), atau aturan database menolak nilainyaconstraint, table, detail

402 out_of_credits tampak seperti ini:

{"error": {"code": "out_of_credits", "message": "this needs 14 credits and 3 are free to spend",
  "details": {"workspaceId": "…", "needed": 13.35, "available": 3.2}}}

Halaman ini sebagai Markdown: /docs/id/api/overview.md