---
title: "Ikhtisar API dan kunci"
description: "REST API Filmsquare: base URL, autentikasi dengan kunci API atau sesi, cara membuat kunci, konvensi, dan error yang akan Anda temui."
url: https://www.filmsquare.ai/docs/id/api/overview/
lang: id
section: api
updated: 2026-11-10
---

# Ikhtisar API dan kunci

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 URL | `https://app.filmsquare.ai/v1` |
| Format | JSON lewat HTTPS |
| Autentikasi | `Authorization: Bearer <API key or session token>` |
| Referensi | `https://app.filmsquare.ai/v1/openapi.json` (OpenAPI 3.1, publik). Lihat [Referensi OpenAPI](https://www.filmsquare.ai/docs/id/api/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).

```bash
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:

```bash
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](https://www.filmsquare.ai/docs/id/working-together/crew-and-roles/).

## Sesi pertama

```bash
# 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](https://www.filmsquare.ai/docs/id/api/webhooks/).

## Konvensi

| Topik | Aturan |
| --- | --- |
| Nama field | Respons 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 diarsipkan | Tidak disertakan di daftar kecuali `includeArchived=true` |
| Menghapus | Baris diarsipkan (`POST …/{id}/archive`), tidak dihapus. Versi, pilihan, persetujuan, dan biaya tidak pernah diubah |
| Idempotensi | Permintaan generate menerima header `Idempotency-Key` (atau `idempotencyKey` di body): kunci yang sama mengembalikan generate yang sudah ada |
| Uang | Biaya dalam kredit, masing-masing dengan tarif saat pekerjaan dimulai; harga kredit dalam euro ada di `GET /v1/pricing` dan [Kredit dan biaya](https://www.filmsquare.ai/docs/id/concepts/credits-and-costs/) |

## Error yang akan Anda temui

Setiap error punya bentuk yang sama:

```json
{"error": {"code": "gate_closed", "message": "finals render once casting, sets, animatic are signed off",
  "details": {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}}}
```

| Status | Kode | Kapan | `details` |
| --- | --- | --- | --- |
| 400 | `validation_error` | Body, query, atau parameter path tidak cocok dengan skema | Daftar masalah validasi |
| 400 | `bad_request`, `invalid_value` | Rute menolak permintaan, atau database tidak bisa membaca sebuah nilai (seperti id yang salah bentuk) | — |
| 400 | `url_not_allowed` | URL webhook atau impor bukan alamat http(s) publik | — |
| 401 | `unauthenticated` | Tidak ada token, atau token yang dicabut atau kedaluwarsa | — |
| 402 | `out_of_credits` | Kredit yang bebas dipakai tidak cukup untuk take ini | `needed`, `available` (kredit) |
| 402 | `plan_limit` | Paket tidak mencakup ini: final di Free, produksi kedua, penyimpanan, seat, bundel tanpa paket | `limit` (`final`, `productions`, `storage`, `seats`, `packs`), `plan` |
| 402 | `budget_exceeded` | Anggaran episode (`budgetCredits` pada episode) akan terlampaui | `episodeId`, `budgetCredits`, `spent`, `inFlight`, `needed` (kredit) |
| 403 | `insufficient_role` | Peran Anda di bawah minimum rute | `required`, `actual` |
| 403 | `not_a_signer` | Anda bukan penyetuju departemen ini | — |
| 403 | `role_exceeds_caller` | Undangan atau kunci dengan peran di atas peran Anda sendiri | — |
| 403 | `not_a_person` | Mengelola kunci dengan kunci pribadi atau koneksi Claude | — |
| 404 | `not_found` | Baris tidak ada, atau tidak boleh Anda lihat | — |
| 409 | `gate_closed` | Final sebelum gerbang terbuka | `episode_id`, `waiting_on` (departemen, atau `placement` untuk shot yang tidak ada di episode mana pun) |
| 409 | `changed_since` | Anda menyetujui versi yang bukan lagi yang terkini | `version` (yang terkini) |
| 409 | `already_signed_off` | Tahap sudah disetujui | — |
| 409 | `element_version_frozen` | Referensi ditambahkan ke versi yang sudah dipakai sebuah take | — |
| 409 | `conflict` | Baris dengan nilai ini sudah ada | — |
| 422 | `foreign_key_violation`, `check_violation`, `not_null_violation` | Baris yang dirujuk tidak ada (atau ada di ruang kerja lain), atau aturan database menolak nilainya | `constraint`, `table`, `detail` |

`402 out_of_credits` tampak seperti ini:

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

## Terkait

- [Webhook](https://www.filmsquare.ai/docs/id/api/webhooks/)
- [Referensi OpenAPI](https://www.filmsquare.ai/docs/id/api/openapi/)
- [Apa yang bisa dikerjakan Claude](https://www.filmsquare.ai/docs/id/claude/tools/): API yang sama lewat MCP
