BölümlerTuzaklar
Başlangıç
Referans
İş akışları
Destek
Tuzaklar
Çağrının başarılı döndüğü ama işin bitmediği yerler: bekleyen transkript, basılmamış deste, kopan bağlantı, sessiz 404.
Transkript hazır değil — çağrı bitti diye hazır sanma
POST …/nodeskartları saniyeler içinde Düğümlerin ve grupların kayıtlı durduğu çalışma yüzeyi; kendi kimliği ve adresi vardırya koyar ama metni koymaz: transkript arka planda çıkar ve dakikalar sürebilir. Cevaptakitranscript: "queued"işin kuyruğa girdiğini söyler, bittiğini değil.- Hazır olduğunu öğrenmenin tek yolu
GET …/summaryile yoklamak: ilk kontrol ~10 saniye sonra, sonra 15 saniyede bir, en çok 10 dakika. - Beklemeden sorarsan model boş kaynakla cevap verir ve bunu sana söylemez.
“skipped” kartın eklenmediği anlamına gelmez
- Bir link için
transcript: "skipped"dönebilir — günlük video kotası kabul etmedi ya da iş kuyruğa alınamadı. Kart yine de tahtaya düşer, sadece metni olmaz.transcriptNotesebebi söyler. - Kart sayısına bakarak “hepsi tamam” demek bu yüzden yanıltıcı;
transcriptalanına bak.
`ask` deste basmaz
- Bir Kanvasta üretilen çok sayfalı görsel çıktı; PNG olarak iner, PDF seçeneği yoktur isteği
asküzerinden gider ama pikselleriasküretmez.deckProposal.act"fire"olduğunda elinde bir PLAN vardır, bir deste değil. - Basma çağrısını sen yaparsın: planı
POST /api/visual/generate’e gönder, dönenjobId’yiGET /api/jobs/{id}ile bekle. - Bu adımı atlayan bir akış “deste üretildi” der ve ortada hiçbir sayfa yoktur.
Gruplama, sohbete giden bağlantıyı koparır
- Bir kartı çerçeveye alırsan o kartın sohbet kartına giden bağlantısı kesilir — bundan sonra sohbeti besleyen şey çerçevenin kendisidir. Kopan bağlantılar
severedEdgeIdsiçinde döner ve okunmazsa fark edilmez. - Doğru sıra: önce grupla, sonra
groupIdile sor.
Desteklenmeyen linkler bütün partiyi düşürür
Kabul edilen üç platform var: Instagram (reel/post/tv), TikTok (video, vm./vt. kısa linkleri dahil) ve YouTube (watch/shorts). Başka her şey 400 döner.
Doğrulama hep-ya-hiç: 20 linkin biri reddedilirse hiçbiri eklenmez ve tahtaya hiçbir şey yazılmaz.
Otomatik bir akışta bu iyi haber — yarım kalmış tahta olmaz — ama hatayı okuyup düzeltmeden aynı gövdeyi tekrar göndermek aynı hatayı verir.
| Biçim | Kabul |
|---|---|
| instagram.com/reel/… · /p/… · /tv/… | evet |
| tiktok.com/@kullanici/video/… | evet |
| vm.tiktok.com/… · vt.tiktok.com/… | evet |
| youtube.com/watch?v=… · youtube.com/shorts/… | evet |
| Instagram profil ya da story adresi | hayır |
| Blog yazısı, haber, PDF, herhangi bir web adresi | hayır |
Kredi harcayan iki kapı
POST …/ask(her tur, token bazlı, tutar küçük) vePOST /api/visual/generate(deste sayfası başına 27–52 Ücretli işlemlerin birimi; sohbet ve deste basımı harcar, transkript çıkarmak harcamaz, tipik bir deste 130–150).- Basım geri alınmaz. Transkript ve video analizi ücretsizdir.
- Bir hata döngüsünün en pahalı hâli, her denemede yeniden basan bir akıştır — otomatik akışlara tekrar tavanı koy.
ask cevabında creditsNotice.exhausted geldiyse bakiye bitmiş demektir. Çağrı hata dönmez, sadece istediğini yapamaz — bu alanı okumayan bir akış sessizce boş cevaplarla devam eder.
404, “yok” değil “senin değil” de olabilir
Senin olmayan bir tahta, hiç olmayan bir tahtayla aynı cevabı verir: 404. İkisi bilerek ayırt edilmiyor — ayırt etmek, başkasının tahtasının var olduğunu doğrulamak olurdu.
Pratikte bu şu demek: 404 aldığında önce tahta kimliğini kontrol et, sonra hangi hesabın anahtarını kullandığını. İki farklı hesapla çalışan bir akışta en sık sebep ikincisidir.
| Gördüğün | İlk bakılacak yer |
|---|---|
| 401 | Anahtar eksik, bozuk ya da iptal edilmiş. Ayarlar’dan kontrol et, tekrar deneme. |
| 403 | Anahtarın açamayacağı bir kapı. Tasarım gereği — başka anahtar denemek işe yaramaz. |
| 404 | Tahta kimliği yanlış ya da tahta başka bir hesapta. |
| 400 | error.message Türkçe söylüyor. Aynı gövdeyi ikinci kez gönderme. |
| 429 | Retry-After kadar bekle, bir kez daha dene, yine olmazsa dur. |
Staging ve üretim aynı adres değil
Üretim https://app.nailingai.co. Staging kendi adresinde çalışır ve bir ortamda ürettiğin tahta kimliği diğerinde çalışmayabilir — yanlış tabana atılan doğru bir çağrı 404 gibi görünür.
Taban adresi akışında tek bir değişkende tut ve o değişkeni tek yerden değiştir. Örneklerdeki $BASE tam olarak bunun için var.
- Bir tahtanın parça tavanı 500. Parti bu tavanı aşacaksa çağrı 400 döner ve hiçbiri eklenmez.
- Her hafta kart ekleyen zamanlanmış bir akış bunu aylar sonra bulur — şimdiden bir bölme planı yap.
Cevap dakikalar sürebilir
ask uzun kaynaklarda dakikalar sürebilir. İstemci zaman aşımını buna göre ayarla.
Zapier gibi adım süresini sınırlayan araçlarda akışı ikiye böl: biri çağrıyı başlatsın, zamanlanmış bir diğeri sonucu toplasın.