API Referansı

StoryboardCanvas API

Üretimde şu anda gönderilen halka açık ve oturum açmış HTTP uç noktaları için referans. Altı uç noktası, tam istek ve yanıt şekilleri, hata kodları ve kopyala-yapıştır curl örnekleri. Projeler, senaryolar ve analizler için daha geniş bir geliştirici API'si yol haritasında yer alıyor.

Gelenekler

Temel URL

Aşağıdaki tüm uç noktalar https://www.storyboardcanvas.aiadresinden sunulmaktadır. Ayrı bir api. alt alan - her şey aynı Next.js uygulaması altında yaşıyor.

Kimlik Doğrulama

Halka açık uç noktalar anonim istekleri kabul eder. İşaretlenmiş uç noktalar Bearer oturum açmış bir Clerk oturumu gerektirir - çoğu istemci bunu oturum açma akışı tarafından ayarlanan bir oturum çerezi olarak taşır. Bugün ayrı bir API anahtarı katmanı yoktur; daha geniş programatik erişim yol haritası.

İçerik türü

Tüm POST uç noktaları kabul eder uygulama/json. Yanıtlar her zaman JSON formatındadır, açıkça belirtilmedikçe (sağlık probe'u da JSON döner).

Hatalar

Hatalar, en azından { hata, kod }içeren bir JSON gövdesi döner. Bazı yollar ayrıca bir detay dizesi döner ve sorunlar[] Zod parse hatalarının dizisi. HTTP durumu, hata kategorisini yansıtır - kötü girdi için 400, eksik kimlik doğrulama için 401, oran limitleri için 429, sunucu hataları için 5xx.

GET/api/healthPublic

Canlılık kontrolü

Uptime izleme ve durum sayfaları tarafından kullanılan ucuz, bağımlılık içermeyen canlılık kontrolü. DB yok, kimlik doğrulama yok, aşağı akış probu yok. 10 saniye boyunca kenarda önbelleğe alındı, Cache-Control: public, max-age=10, s-maxage=10 ile - daha sık çağrıldığında aynı yük döndürülür.

Yanıt (200)
{
  "ok": true,
  "version": "a1b2c3d",        // dağıtılan commit SHA'nın ilk 7 karakteri
  "region": "iad1",            // hizmet verilen bölge veya "bilinmiyor"
  "timestamp": "2026-04-26T10:15:00.000Z"
}
Hatalar
DurumKodAnlam
200-Lambda erişilebilir olduğunda her zaman 200. Bir non-200, platformun kendisinin kapalı olduğu anlamına gelir (soğuk başlatma hatası, ağ).
Örnek
curl https://www.storyboardcanvas.ai/api/health
POST/api/contactPublic

İletişim formu

Destek kutusuna bir iletişim formu gönderimi gönderir. /contact sayfası tarafından kullanılır. IP başına dakikada 5 istekle sınırlıdır. Tüm girişler, çıkış e-posta gövdesine yerleştirilmeden önce HTML ile kaçış yapılır.

İstek gövdesi
{  
  "name":    "Alex Chen",                       // zorunlu, 1-200 karakter  
  "email":   "alex@example.com",                // zorunlu, geçerli e-posta  
  "subject": "Studio planı hakkında soru",     // zorunlu, 1-500 karakter  
  "message": "Merhaba - Birkaç sorum vardı..."  // zorunlu, 1-10000 karakter  
}
Yanıt (200)
{ "success": true }
Hatalar
DurumKodAnlam
400geçersiz-gövdeGerekli bir alan eksik veya bir alan uzunluk sınırını aşıyor.
429hız sınırlıBu IP'den son bir dakikada 5'ten fazla gönderim yapıldı. Retry-After başlığı içerir.
500sunucu-hatasıE-posta iletimi başarısız oldu. Form güvenli bir şekilde yeniden deniyor.
Örnek
curl -X POST https://www.storyboardcanvas.ai/api/contact \
  -H "Content-Type: application/json" \
  -d '{"name":"Alex","email":"alex@example.com","subject":"Merhaba","message":"Merhaba"}'
POST/api/billing/checkoutBearer

Bir Stripe Checkout oturumu başlat

Oturum açmış kullanıcı için bir Stripe Checkout Oturumu oluşturur ve barındırılan ödeme URL'sini döner. client_reference_id, faturalama webhook'unun aboneliği ek bir Clerk gidiş-dönüşü olmadan çözebilmesi için Supabase sahibi uuid'sidir. Eğer bu kullanıcı için daha önce bir Stripe müşterisi varsa, müşteri kimliğini yeniden kullanırız (tekrar eden müşteriler yok, çift denemeler yok).

İstek gövdesi
{
  "plan":     "solo" | "team" | "studio" | "agency" | "network" | "broadcaster",
  "interval": "ay" | "yıl"   // isteğe bağlı, varsayılan "ay"
}
Yanıt (200)
{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}
Hatalar
DurumKodAnlam
401yetkisizTalepte geçerli bir Clerk oturumu yok.
400geçersiz-gövdePlan eksik veya kabul edilen enum değerlerinden biri değil.
503stripe_yapılandırılmamışBu ortamda faturalama etkin değil. /billing UI bunu bir toast olarak gösterir.
500sunucu-hatasıStripe API çağrısı başarısız oldu. Geri çekilme sonrası tekrar denemek güvenli.
Örnek
curl -X POST https://www.storyboardcanvas.ai/api/billing/checkout \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=<clerk-session-cookie>" \
  -d '{"plan":"studio","interval":"year"}'
GET/api/billing/statusBearer

Abonelik durumunu oku

Kullanıcının oturum açmış olduğu mevcut planını, durumunu, günlük kredi tahsisatını ve Stripe müşteri kimliğini döndürür. Yanıt, her zaman gerçeği yansıttığı için Clerk publicMetadata yerine Supabase'den (webhook'un sakladığı) okunur. Herhangi bir hata durumunda, UI'nın asla döngüye girmemesi için yumuşak bir şekilde ücretsiz / hiç yük ile sonuçlanır.

Yanıt (200)
{
  "plan":               "ücretsiz" | "bireysel" | "takım" | "stüdyo" |
                        "ajans" | "ağ" | "yayıncı",
  "status":             "aktif" | "deneme" | "geçmiş_ödemeli" |
                        "iptal edildi" | "hiçbir",
  "credits_daily":      sayı,
  "current_period_end": "2026-05-26T00:00:00Z" | null,
  "stripe_customer_id": "cus_..." | null,
  "has_subscription":   boolean
}
Hatalar
DurumKodAnlam
401yetkisizTalepte geçerli bir Clerk oturumu yok.
200-Herhangi bir iç hata durumunda, rota 200 durumu ile ücretsiz / hiç yük döndürür, böylece UI render etmeye devam eder.
Örnek
curl https://www.storyboardcanvas.ai/api/billing/status \
  -H "Cookie: __session=<clerk-session-cookie>"
POST/api/account/delete-requestBearer

Hesap silme talebi (GDPR)

Oturum açmış kullanıcı için bekleyen bir silme talebi oluşturur. Tıklama ile otomatik silme yapmıyoruz - bir yönetici, Stripe'ın işlemi tamamlamasından sonra talebi manuel olarak işler. Kullanıcı, niyetini kanıtlamak için kendi birincil e-posta adresini yazmalıdır (Clerk'in kayıtlı e-posta adresi ile büyük/küçük harf duyarsız eşleşme).

İstek gövdesi
{
  "confirmEmail": "alex@example.com",         // gerekli, hesap e-postası ile eşleşmelidir
  "reason":       "Üretimi tamamlamak"       // isteğe bağlı, <=2000 karakter
}
Yanıt (200)
{
  "ok": true,
  "saved": true,
  "request_id": "uuid",
  "submitted_at": "2026-04-26T10:15:00.000Z"
}
Hatalar
DurumKodAnlam
401yetkisizTalepte geçerli bir Clerk oturumu yok.
400geçersiz-gövdeconfirmEmail eksik veya sebep 2000 karakter sınırını aşıyor.
400email-uyumsuzconfirmEmail, hesabın birincil e-postasıyla eşleşmiyor.
200tablo eksikBu ortamda silme tablosu sağlanmadığında { saved: false, table_missing: true } ile döndü.
500db-hatasıVeritabanı yazma işlemi başarısız oldu. Yeniden denemek güvenli.
Örnek
curl -X POST https://www.storyboardcanvas.ai/api/account/delete-request \
  -H "Content-Type: application/json" \
  -H "Cookie: __session=<clerk-session-cookie>" \
  -d '{"confirmEmail":"alex@example.com","reason":"Wrapping production"}'

Listelenmeyen bir uç noktaya mı ihtiyacınız var?

Projeleri, senaryoları, çözümlemeleri, çekim listelerini, karakterleri ve programlamayı kapsayan daha geniş bir geliştirici API'si, lansman sonrası yol haritasında yer alıyor. Ne inşa etmek istediğinizi bize bildirin iletişim formu ve kullanım durumunuzu v1 yüzeyine dahil edeceğiz.

Storyboard Canvas · the complete production suite

The complete script-to-screen suite - start free

Twenty synchronised apps, one project file. Every app on every plan - pick a tier by team size, not features.

Get started