Fal.ai Butler

Projeni bitirdin, reklam vermen gerekiyor — ama elinde video yok ve video prodüksiyonu bilmiyorsun.

fal-butler, projeni okuyup ürününü anlayan bir Claude Code plugin'i. Kısa bir röportajla kampanyayı öğrenir; sonra senarist, görüntü yönetmeni, hareket yönetmeni, ses tasarımcısı, kurgucu ve prompt mühendisinden oluşan bir ekip senin iki cümlelik tarifini profesyonel bir reklam kurgusuna çevirir.

Sen şunu yazarsın:

"Kadın, 30'larında, ofiste çalışıyor, yorgun başlıyor mutlu bitiyor."

Karşılığında fal.ai'a import edilmeye hazır bir workflow.json alırsın: altı sahne, birbirine görsel olarak zincirlenmiş, karakteri baştan sona aynı, seslendirmeli, müzikli, altyazılı ve platforma göre kesilmiş.

Bu plugin hiç para harcamaz

Plugin hiçbir modeli çalıştırmaz — bu bir söz değil, mekanizma: agent'ların araç listesinde yalnızca beş okuma aracı var (search_models, get_model_schema, get_pricing, recommend_model, search_docs). run_model, submit_job ve upload_file listede yok, dolayısıyla çağrılamaz. Depodaki denetçi joker MCP iznini test hatası sayar, yani bu garanti kazara gevşetilemez.

Üretimi sen fal panelinden, gerçek fiyatı gördükten sonra başlatırsın.

Kurulum

1. Plugin'i kur

/plugin marketplace add mertagralii/fal.ai-butler
/plugin install fal-butler

2. Anahtarını ver ve başla

https://fal.ai/dashboard/keys adresinden anahtarını al, sonra tek komut:

/fal-butler:setup <fal-api-anahtarın>

Ürün sitesi de varsa aynı satırda verebilirsin:

/fal-butler:setup <anahtarın> https://urunum.com

Bu kadar. Anahtar ~/.claude/settings.json dosyana yazılır, bağlantı test edilir, katalog önbelleğe alınır ve ürün profilin çıkarılır — hepsi tek seferde.

Ürününü nereden öğreniyor

Setup sana sorar:

Site genelde daha iyi kaynaktır: repo'da ürünün kodu var, sitede ürünün hedef kitleye söylediği cümle var — reklam için aradığımız tam olarak bu. İkisi çelişirse site kazanır.

Statik siteler doğrudan okunur; JavaScript ile render edilen sitelerde plugin'in getirdiği Playwright devreye girer ve sayfayı gerçekten çalıştırıp okur.

Güvenlik: site içeriği veri olarak işlenir, talimat olarak değil. Sayfada plugin'e yönelik bir yönerge bulunursa uygulanmaz — sana alıntılanır ve işlem durur. Yalnızca verdiğin alan adında kalınır, dış bağlantılar takip edilmez, giriş isteyen sayfada durulur.

Anahtarı zaten kayıtlıysa argümansız çalıştır: /fal-butler:setup

Anahtar ~/.claude/settings.json'a yazılır — kullanıcı kapsamı, git'e girmez. Projenin içindeki .claude/settings.json commit edilir; oraya asla yazılmaz. Kayıt sonrası anahtarın tamamı ekrana basılmaz, yalnızca son 4 karakteri gösterilir.

Anahtarı kendin koymak istersen

~/.claude/settings.json dosyasına şu bloğu ekle ve Claude Code'u bir kez yeniden başlat:

{
  "env": {
    "FAL_KEY": "senin-anahtarin"
  }
}

# Windows — kalıcı olarak kullanıcı ortamına yazar
[Environment]::SetEnvironmentVariable('FAL_KEY', 'senin-anahtarin', 'User')

# macOS / Linux — kalıcılık için kabuk profiline ekle
export FAL_KEY="senin-anahtarin"

Hangi yöntemi kullanırsan kullan, setup bağlantıyı gerçekten test eder — anahtar fal'a ulaşmıyorsa sana söyler ve diğer yönteme geçmeni önerir.

Komutlar

/fal-butler:campaign --quick sekiz soru yerine dördünü sorar; kalanını ürün profilinden türetir ve türettiklerini planda listeler.

Nasıl çalışıyor

Röportaj

Sorular tek tek gelir, her birinin ürün profilinden türetilmiş varsayılanı vardır: amaç, platform ve süre, anlatım biçimi, karakter, ton, dil, kapsam (seslendirme / müzik / altyazı — her biri ayrı ayrı kapatılabilir), CTA.

Dokuz adımlık zincir

0. fal-compiler ─── modelleri seçer, şemaları ve fiyatları çeker
1. fal-director ─── hook, sahne beat'leri, süre dağılımı, seslendirme metni, karakter bible
2. fal-dop ──────── plan ölçeği, lens, ışık kurulumu, palet, kompozisyon
3. fal-animator ─── hareket dili + zincirleme grafiği
4. fal-audio ────── TTS, müzik, miksaj + konuşma süresi denetimi
5. fal-animator ─── süre düzeltmesi (yalnızca gerekirse, tek tur)
6. fal-editor ───── kesim ritmi, geçişler, altyazı yerleşimi, montaj yapısı
7. fal-promptsmith ─ hepsini hedef modelin konuştuğu dile çevirir
8. fal-compiler ─── workflow.json'u derler ve doğrulayıcıdan geçirir

Model seçiminin başta olması gerekiyor: fal-animator klip süre sınırını, fal-promptsmith prompt lehçesini modelin şemasından okuyor.

Kullanıcı sinematografi bilmez — fal-dop "ofiste" tarifini "geniş pencereden yumuşak yan ışık, sabah, 35 mm his, hafif dolly-in" diye açar. Sen bunu düz Türkçe olarak görürsün, ham prompt olarak değil.

Karakter neden aynı kalıyor

karakter-sayfası ──┬──────────────────────────────────→ anahtar-kare-2 ← son-kare-1
                   │                                          ▲
                   ├──→ anahtar-kare-1 → video-1 → son-kare-1 ┘
                   │
                   └──────────────────────────────────→ anahtar-kare-3 ← son-kare-2

Önce 3–5 açılı bir karakter sayfası üretilir. Her sahnenin başlangıç karesi ondan image-edit ile türer; sahne videoya çevrilir; son karesi bir sonraki sahnenin referansına eklenir.

Karakter sayfası her sahneye bağlı kalır — yalnızca önceki sahneye zincirlemek sapmayı biriktirir ve altıncı sahnede başka biri çıkar. Seed kampanya başına sabitlenir ve brief.md'ye yazılır, böylece revizyonlar deterministik olur.

Onay kapısı

Adım 7'den sonra, hiçbir dosya yazılmadan karşına düz Türkçe bir plan gelir:

Sahne 2 — Büyütme (0:06–0:14) Ayşe ekrana bakıyor, bildirimler yığılıyor. Yakın plan, sabah ışığı, soğuk ton. Ses: "Bildirimler bitmiyor." Model: <endpoint> · 8 sn · ~$X

Altı sahne, kullanılacak modeller, toplam tahmini maliyet ve uyarılar. Onaylamazsan hiçbir şey yazılmaz.

Doğrulama

Üretilen workflow.json bağımsız bir script'ten geçer: düğüm referansları çözülüyor mu, döngü var mı, contents.schema.input tanımlı mı, düğüm id'leri anahtarlarıyla uyuşuyor mu, kullanılan endpoint'ler katalogda gerçekten duruyor mu.

Geçmeyen dosya sana verilmez. Hatalı JSON'u teslim etmek, hatayı fal'ın import ekranında öğrenmek demek.

Revizyon

fal'da fiyatı gördün, pahalı geldi:

/fal-butler:revise maliyeti yarıya indir

Önce paranın nereye gittiğini gösterir, sonra somut seçenekler sunar — her birinin ne kadar düşürdüğü ve neyi feda ettiğiyle birlikte. İki şeyi asla önermez: karakter sayfasını kaldırmak ve zincirlemeyi kaldırmak. Onlar ucuzlatma değil, kampanyayı çöpe atmak.

Kurgu revizyonu da aynı komuttan: "üçüncü sahne daha aydınlık" tek düğüm değiştirir. Her değişiklikten önce eski JSON revisions/ altına zaman damgasıyla kopyalanır.

Neden model adı göremezsin

Bu depoda hiçbir fal model adı sabit yazılı değildir. Katalog, şemalar ve fiyatlar çalışma anında fal MCP'den çekilip yerel önbelleğe yazılır (7 gün TTL). fal yeni bir video modeli çıkardığında ya da bir endpoint kaldırdığında plugin'i güncellemen gerekmez.

Tek istisna ffmpeg-api ailesidir — o bir üretim modeli değil, montaj altyapısı. Şeması ve fiyatı yine canlı okunur.

Sorun giderme: 401 alıyorsan

İki bambaşka sorun aynı kodla geliyor. fal'ın mesajını oku:

"malformed Authorization header" — Windows'un klasik tuzağı

[Environment]::SetEnvironmentVariable(...,'User') yalnızca kayıt defterine yazar. Zaten açık olan bir terminal kendi ortam bloğunu başladığı andan taşır ve içinden başlattığı her programa o eski bloğu devreder.

Yani Claude Code'u kapatıp açmak yetmez — onu doğuran terminal hâlâ eski ortamda.

Çözüm sırası:

1. En kolayı: /fal-butler:setup <anahtarın> çalıştır. Anahtar ~/.claude/settings.json'a yazılır, işletim sistemi ortamına hiç bağlı kalmazsın, tuzak tamamen ortadan kalkar.
2. Ortam değişkeninde ısrar ediyorsan: tüm terminal pencerelerini kapat, yeni bir PowerShell aç ve Claude Code'u başlatmadan önce doğrula — $env:FAL_KEY.Length anahtarın uzunluğunu yazmalı.
3. Hemen lazımsa: $env:FAL_KEY = [Environment]::GetEnvironmentVariable('FAL_KEY','User'); claude

Anahtarın geçerli mi — ücretsiz test

Model çalıştırmadan, yalnızca JSON-RPC el sıkışmasıyla. Para harcamaz:

$k = [Environment]::GetEnvironmentVariable('FAL_KEY','User')
$body = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}'
Invoke-WebRequest -Uri 'https://mcp.fal.ai/mcp' -Method Post -Headers @{
  'Authorization'='Key '+$k; 'Accept'='application/json, text/event-stream'; 'Content-Type'='application/json'
} -Body $body -UseBasicParsing | Select-Object -ExpandProperty StatusCode

200 → anahtar geçerli, sorun taşımada. 401 → anahtar geçersiz.

Import — sahada doğrulandı

2026-08-05: üretilen workflow.json fal Workflow Builder'a import edildi ve hatasız kabul edildi (25 düğümlük bir kampanya). Biçim doğru.

Import fal panelinden elle yapılır. Programatik oluşturma mümkün değil: POST /workflows ADMIN anahtarı ister, normal FAL_KEY 403 döner.

Bunun bir sonucu var: workflow'un fal tarafından kabul edilip edilmeyeceği API'den doğrulanamaz, dolayısıyla validate-workflow.mjs tek savunma hattıdır. O yüzden doğrulayıcı fal'ın contents seviyesindeki zorunlu alanlarını ve montaj düğümünün track yapısını da denetler — ikisi de sahada workflow'u çalışamaz hale getiren hatalardı.

Montajın üç sert sınırı

fal'ın ffmpeg-api/compose şeması gereği şunlar yapılamaz — plugin bunları baştan bilir ve plana yazmaz:

Getirdiği MCP sunucuları

context7 ve playwright ilk açılışta npx ile indirilir. Aynı sunucuları başka bir plugin de getiriyorsa ayrı ad alanlarında çalışırlar — çakışmaz, ama iki süreç açılır.

Ürettiği dosyalar

Hepsi senin repo'nda, .fal-butler/ altında — git'te izlenebilir:

.fal-butler/
  product.md                      # ürün profili — bir kez üretilir
  cache/                          # model şemaları ve fiyatlar (7 gün TTL)
  campaigns/2026-08-05-lansman/
    brief.md                      # röportaj cevapların + seed + sabit karakter bloğu
    storyboard.md                 # sahne sahne kurgu, düz Türkçe
    workflow.json                 # fal.ai'a import edeceğin dosya
    cost.md                       # maliyet dökümü ve ucuzlatma seçenekleri
    revisions/                    # her revizyonun öncesi

.gitignore'una şunu ekle:

.fal-butler/cache/

Önbellek yeniden üretilebilir; repo'da yer kaplamasın.

Geliştirme

Bağımlılık yok. Node.js ≥ 20 yeterli.

npm test                          # 69 birim testi — ağ çağrısı yapmaz, para harcamaz
node scripts/validate-plugin.mjs  # plugin yapısal bütünlüğü

validate-plugin.mjs şunları denetler: manifest alanları, skill adı ↔ dizin adı, agent adı ↔ dosya adı, anılan references/*.md dosyalarının varlığı, model değerinin geçerliliği, boş agent gövdesi ve joker MCP izni.

Tasarım dokümanı: docs/superpowers/specs/ — uygulama sırasında bilerek sapılan noktalar §16'da gerekçeleriyle listeli.

Lisans

MIT — bkz. LICENSE.