Durum sorgulama

Webhook neden henüz yok

v1’de callback yok. Webhook bir teslimat garantisidir: yeniden denemeler, imzalar, tekrar koruması, saatlerce ısrarla denenen bir adres. Yarısını yayınlamak hiç yayınlamamaktan kötü olurdu, çünkü entegrasyon o garantiye güvenir. Durum sorgulama sıkıcı bir yöntem ama işini yapıyor. v1’den sonraki ilk işimiz webhook.

API üzerinden oluşturulan bir kayıt, uygulamalardaki kayıtların gönderdiği bildirimi ve “deşifre metniniz hazır” e-postasını da göndermez: bir entegrasyon o kadar çok kayıt oluşturur ki ikisi de birinin gelen kutusunda gürültüden başka bir şey olmaz.

Dört durum

Sözlük bilerek bu dört kelimeden ibaret: hattın içeride daha fazla durumu var, ama onlara göre dallanan bir entegrasyon, bir işi ikiye böldüğümüz gün çalışmaz olurdu. completed ile failed birer son durum; onlardan sonra hiçbir şey değişmez.

progress alanı

GET /transcriptions/{id} yanıtında bir progress nesnesi bulunur. İlerleme çubuğunu bununla çizin; işin bitip bitmediğine ise buradan karar vermeyin — bunu yalnızca status söyler.

{
  "id": "0f2f5f6a-2c6c-4f4e-9d1e-5d8f2a1b3c4d",
  "status": "processing",
  "duration_seconds": 3742,
  "progress": { "step": "transcribe", "percent": 46, "indeterminate": false },
  "failure_reason": null
}

• percent, ölçebildiğimizde 0–100 arası bir sayı; ölçemediğimizde null olur.
• indeterminate alanı true ise iş sürüyor ama ne kadarının bittiği ölçülemiyor demektir. Ölçülemeyen tek aşama da bu değil: indirme, dönüştürme ve tamamlama adımlarında sayı hiç gelmez. Her iki durumda da sayıya takılı bir çubuk yerine dönen bir gösterge kullanın.
• step kabaca o an ne yapıldığını anlatır. Ekranda göstereceğiniz bir etiket olarak görün, dallanacağınız bir değer olarak değil: adımlar v1 içinde değişebilir.

Liste endpointi daha hafif bir progress döner: yalnızca adım. Bir kaydın ne kadar ilerlediği o kayda sorulacak bir sorudur; tek tek sorun.

Önerilen aralıklar

Deşifre, kaydın süresinin küçük bir bölümü kadar sürer. Makul bir plan şöyle:

• İlk kontrolü 10 saniye sonra yapın. Hiçbir kayıt bundan önce bitmiyor; hemen sormak yalnızca bir isteğinize mal olur.
• Sonra 5 saniyede bir sorun. On dakikanın altındaki kayıtlar için bu tempo yeterli.
• Uzun kayıtlarda aralığı açın — her seferinde iki katına çıkarın, 30 saniyeyi tavan kabul edin.
• Kaydın süresinin iki katı artı on dakika sonra vazgeçin ve bir insanı haberdar edin. O noktaya kadar kıpırdamamış bir kayıt, daha uzun bir bekleyişi değil destek ekibiyle bir konuşmayı gerektirir.

5 saniyede bir istekle tek bir kayıt, dakikadaki 120 isteğin 12’sini harcar. Bu, aynı anda 10 kaydı beklemeye yeter; daha fazlasını yürütüyorsanız aralığı daha erken açın. Bkz. hız sınırları.

Bir sorgulama döngüsü

Retry-After başlığına uyun. 429 aldığınızda ne kadar bekleyeceğinizi bu başlık söyler; 5xx ise hata değil, bekleme sebebidir.

# A shell loop, for completeness -- in production this belongs in your application.
until [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; do
  sleep 5
  STATUS=$(curl -s "https://heartotext.com/api/public/v1/transcriptions/$ID" \
    -H "Authorization: Bearer $H2T_API_KEY" | jq -r .status)
done

Kayıt başarısız olduğunda