---
title: "API'ye genel bakış ve anahtarlar"
description: "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."
url: https://www.filmsquare.ai/docs/tr/api/overview/
lang: tr
section: api
updated: 2026-11-10
---

# API'ye genel bakış ve anahtarlar

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](https://www.filmsquare.ai/docs/tr/api/openapi/) |

## 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).

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

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

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

## İlk oturum

```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` `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](https://www.filmsquare.ai/docs/tr/api/webhooks/) 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](https://www.filmsquare.ai/docs/tr/concepts/credits-and-costs/) içinde |

## Karşılaşacağın hatalar

Her hata aynı biçimdedir:

```json
{"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:

```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}}}
```

## İlgili

- [Webhook'lar](https://www.filmsquare.ai/docs/tr/api/webhooks/)
- [OpenAPI başvurusu](https://www.filmsquare.ai/docs/tr/api/openapi/)
- [Claude neler yapabilir](https://www.filmsquare.ai/docs/tr/claude/tools/): aynı API, MCP üzerinden
