BeeSTT API

BeeSTT API, çağrı kayıtlarını BeePanel'in kullandığı ön ödemeli kredilerle kendi yazılımınızdan transkript eder. Transkripti konuşmacı etiketleri, kısa bir özet ve diliyle birlikte tek bir JSON yanıtında döndürür. Pro lisans değil, bir müşteri portalı hesabı ve bir API anahtarı gerektirir.

Tüm istekler HTTPS üzerinden https://beestt.beepanel.io adresine gider.

Başlamadan önce

• BeeSTT kredisi olan bir müşteri portalı hesabı. Bu sitenin üstündeki Portal girişi ile oturum açın. Kredi fiyatları fiyat sayfasındadır.
• Bir API anahtarı. Portalda BeeSTT > API anahtarları'nı açın ve Anahtar oluştur'u seçin; ilk anahtarınızda portal güncel koşulları Kabul et ve anahtar oluştur ile kabul etmenizi ister. Anahtarı hemen kopyalayın: yalnızca bu seferlik gösterilir.
• Kabul edilen biçimlerden birinde kayıtlar: Ogg/Opus, PCM WAV ya da GSM 6.10 WAV (WAV49). BeeSTT biçimi dosyanın içeriğinden okur; dosya adı ve uzantısı önemli değildir.

Kimlik doğrulama

Anahtarı her isteğin Authorization başlığında gönderin:

Authorization: Bearer bstt_...

Anahtar bstt_ ile başlar ve 48 karakterdir. Onu bir parola gibi gizli tutun. Açığa çıkarsa portalda yanındaki İptal et'i seçin ve yeni bir anahtar oluşturun; iptal edilen anahtarla daha önce kabul edilmiş işler yine de ücretlendirilir ve sonuçları o anahtarla artık okunamaz. İptal etmeden önce süren işlerin bitmesini bekleyin.

Anahtarı denetlemek

GET /v1/balance anahtarın hesap bakiyesini döndürür ve ücretsizdir. Anahtarın çalıştığını denetlemek için kullanın:

curl https://beestt.beepanel.io/v1/balance \
  -H "Authorization: Bearer $BEESTT_API_KEY"

{ "success": true, "data": { "balance_micro_usd": 4250000 } }

balance_micro_usd, ABD dolarının milyonda biri cinsinden bir tamsayıdır.

Bir kaydı transkript etmek

Kaydı multipart/form-data olarak POST /v1/audio/transcriptions adresine gönderin:

curl https://beestt.beepanel.io/v1/audio/transcriptions \
  -H "Authorization: Bearer $BEESTT_API_KEY" \
  -F model=beestt-1 \
  -F file=@call.wav

language ya da prompt gibi diğer tüm alanlar yok sayılmaz, hatayla reddedilir. BeeSTT dili kendisi algılar.

BeeSTT sonuç için en fazla 10 saniye bekler. Bu sürede biten bir kayıt sonuçla birlikte 200 döndürür. Bir 200, bir 202 ve başarısız bir işin hatası, işin kimliğini Beestt-Job-Id başlığında taşır.

{
	"task": "transcribe",
	"language": "tr",
	"text": "Aradığınız için teşekkürler. Nasıl yardımcı olabilirim?",
	"segments": [
		{
			"type": "transcript.text.segment",
			"start": 0,
			"end": 4,
			"text": "Aradığınız için teşekkürler. Nasıl yardımcı olabilirim?",
			"speaker": "A"
		}
	],
	"beestt": {
		"job_id": "01928f6e-6f3c-7a1b-9c2d-3e4f5a6b7c8d",
		"result_status": "ok",
		"interaction_state": "normal",
		"summary": "Temsilci arayanı karşılıyor ve yardım öneriyor.",
		"speakers": [{ "id": "A", "name": null }]
	}
}

• language, kaydın baskın dilinin ISO 639-1 kodudur; belirlenemezse und olur. Başka dillerdeki konuşmalar bu dile çevrilir ve beestt.translated_from_languages o dilleri listeler.
• segments, metni saniye cinsinden başlangıç ve bitişiyle ve bir konuşmacı etiketiyle (ilk konuşma sırasına göre A, B vb.) taşır. beestt.speakers bir konuşmacının adını yalnızca kayıtta söyleniyorsa verir; aksi hâlde name değeri null olur.
• beestt.result_status değeri ok, partial (bir kısmı eksik ama kullanılabilir metin), no_usable_speech (sessizlik ya da anlaşılmayan konuşma) ya da language_unsupported olur. Son ikisi metin taşımaz.
• beestt.interaction_state, modelin görüşmenin nasıl geçtiğine dair tahminidir: positive, normal, tense, problematic ya da undetermined. Ticari bir sonuç değil, bir tahmindir.
• beestt.summary, beestt.speakers ve beestt.translated_from_languages boşsa yanıtta yer almaz.

Uzun kayıtlar

10 saniye içinde bitmeyen bir kayıt 202 döndürür:

{
	"id": "01928f6e-6f3c-7a1b-9c2d-3e4f5a6b7c8d",
	"object": "audio.transcription.job",
	"status": "processing"
}

Location başlığı işin yolunu, Retry-After ise beklenecek saniyeyi verir. Kaydı yeniden göndermeyin; bunun yerine işi sorgulayın. Aşağıdaki yanıt kısaltılmıştır:

curl https://beestt.beepanel.io/v1/jobs/01928f6e-6f3c-7a1b-9c2d-3e4f5a6b7c8d \
  -H "Authorization: Bearer $BEESTT_API_KEY"

{
	"success": true,
	"data": {
		"job_id": "01928f6e-6f3c-7a1b-9c2d-3e4f5a6b7c8d",
		"status": "completed",
		"result_expired": false,
		"result": { "task": "transcribe", "language": "tr", "text": "..." }
	}
}

• status iş sürerken received, processing ya da billing_pending, sonunda completed ya da failed olur. Başarısız bir iş hata kodu olmadan yalnızca bir failure_message taşır ve ücretlendirilmez.
• result, bir 200 yanıtının döndürdüğü nesnenin aynısıdır; iş bitene kadar null olur.
• Sonuç sınırlı bir süre saklanır. Bu süreden sonra iş yine yanıt verir, ama result_expired değeri true, result değeri null olur.
• İşi sorgulamak ücretsizdir.

Yeni transkript istemek

Bir sonuç hatalıysa aynı kaydı önceki sonuç hakkında geri bildirimle yeniden gönderin:

curl https://beestt.beepanel.io/v1/audio/transcriptions \
  -H "Authorization: Bearer $BEESTT_API_KEY" \
  -F model=beestt-1 \
  -F file=@call.wav \
  -F beestt_feedback_code=text_inaccurate \
  -F beestt_feedback_job_id=01928f6e-6f3c-7a1b-9c2d-3e4f5a6b7c8d

beestt_feedback_job_id, bu kaydın aynı anahtarla yapılmış önceki tamamlanmış işidir. speakers_mixed, text_incomplete, text_inaccurate ve summary_poor yeni bir transkript üretir ve yeni bir transkript olarak ücretlendirilir. other ile geri bildirim kaydedilir ve saklanan sonuç, herhangi bir yeniden gönderim gibi ücretlendirilerek yeniden döndürülür.

Ücretlendirme

• partial, no_usable_speech ve language_unsupported dahil her tamamlanan sonuç ücretlendirilir. Fiyatlar ve ücretlendirilen en kısa süre fiyat sayfasındadır.
• Başarısız bir iş, reddedilen bir istek ve anahtar için belirlenmiş bir ücretlendirme sınırını aşan bir kayıt ücretlendirilmez.
• Aynı kaydı işi hâlâ sürerken yeniden göndermek ücretsiz olarak aynı işi döndürür. İş bittikten sonra yeniden göndermek yeniden ücretlendirilir: önceki sonuç hâlâ saklanıyorsa BeeSTT aynı sonucu döndürür. Yeni bir transkript için geri bildirim gönderin; bkz. Yeni transkript istemek.
• Bakiye bir kaydı karşılamıyorsa BeeSTT onu transkripsiyona başlamadan insufficient_balance ile reddeder.

OpenAI istemci kütüphanesi kullanmak

POST /v1/audio/transcriptions, yukarıda listelenen alanlar için OpenAI Audio API'nin transkripsiyon uç noktasının istek ve yanıt yapısını izler. Resmî OpenAI Go kütüphanesiyle test edilmiştir; temel adresi ayarlamaya izin veren diğer OpenAI istemci kütüphanelerinin de aynı şekilde çalışması beklenir ama test edilmemiştir. Böyle bir kütüphane, BeeSTT anahtarı, beestt-1 modeli ve diarized_json yanıt biçimiyle https://beestt.beepanel.io/v1 adresine istek gönderebilir. Şunlara dikkat edin:

• kütüphane bir 202 yanıtını başarı sayabilir; HTTP 202 durumunu ya da audio.transcription.job değerli object alanını denetleyin, ardından işi sorgulayın;
• GET /v1/jobs/{job_id} ve GET /v1/balance BeeSTT'nin kendi uç noktalarıdır; onları doğrudan çağırın;
• beestt nesnesi kütüphanenin tanımayabileceği bir eklemedir; onu ham JSON'dan okuyun;
• kütüphane başarısız istekleri kendiliğinden yeniliyorsa, yanıtı kaybolan bir gönderimin yeniden denenmesi yeniden ücretlendirilebilir; gönderimler için otomatik yeniden denemeyi kapatın.

Hatalar

POST /v1/audio/transcriptions hataları şu yapıda döndürür:

{
	"error": {
		"message": "The requested model does not exist. Submit the generic BeeSTT model.",
		"type": "invalid_request_error",
		"param": "model",
		"code": "model_not_found"
	}
}

GET /v1/jobs/{job_id} ve GET /v1/balance ise şu yapıda döndürür:

{
	"success": false,
	"error": {
		"code": "job_not_found",
		"message": "No such job exists for this API key."
	}
}

Mesajlar İngilizcedir. Mesaj metnine değil, code değerine göre işlem yapın.

İlgili makaleler

• Çağrı transkripsiyonu
• Destek alma

OpenAI, sahibinin ticari markasıdır. BeeSTT bağımsız bir hizmettir; OpenAI ile bağlantılı değildir ve OpenAI tarafından onaylanmamıştır.