Konuşmayı metne dönüştürme API’si

Bu API, tamamlanmış ses dosyalarını kuyruğa alınan işler olarak yazıya döker. Bir dosya gönderin, dönen iş kimliğini saklayın ve işlem tamamlanana kadar işi sorgulayın. Her isteği HTTPS üzerinden hesabınıza ait kimlik bilgileriyle gönderin; örneklerde gösterilen HTTP Basic kimlik bilgilerini veya şu bölümde açıklanan API belirtecini kullanın: Kimlik doğrulama. Kimlik bilgilerini sunucunuzda saklayın.

Uç noktalar

İki API sunucusu, https://api.multi.tel ve uyumluluk sunucusu https://api.multitel.net, hesap kapsamındaki aynı işleri, idempotans anahtarlarını, sınırları ve faturalandırmayı paylaşır. Yükleme kodlamaları ve yanıt zarfları farklıdır; bu nedenle uygun yanıt ayrıştırıcısıyla birlikte tutarlı olarak aynı sunucuyu kullanın.

Sunucu api.multi.tel üzerinde tüm yollar /v1/speech-to-text önekiyle de kullanılabilir; bu önek şu önekin yerine geçer: /v3/speech_to_text, örneğin POST /v1/speech-to-text/estimate. Şu sunucuda: api.multitel.net, şu yolları kullanın: /v3/speech_to_text.

Hizmet bilgileri yanıtı şu alanları bildirir: mode (batch), realtime (false), paidEnabled (yeni ücretli gönderimlerin şu anda kabul edilip edilmediği), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) ve maxUploadBytes (26214400); ayrıca şu alanda kısa bir açıklama bulunur: description. Bu bilgileri sorgulamak ücretsizdir ve ücretli gönderimler devre dışıyken de çalışır; yalnızca hizmetin bütünü kullanılamadığında 503 transcription_unavailable döndürür.

Ses dosyası hazırlama

En fazla 25 MiB (26,214,400 bayt) boyutunda ve en fazla 2 saat (7,200 saniye) uzunluğunda tamamlanmış bir ses dosyası kullanın. Gönderim sırasında dosya, ses akışı içeren MP3, WAV, Ogg, FLAC, MOV veya Matroska ortamı olarak tanınmalı ve meta verilerindeki süre sıfırdan büyük, en fazla 7,200 saniye olmalıdır. Tanınan ancak bu denetimleri geçemeyen bir dosya 422 unsupported_audio ile reddedilir. Bu biçimlerin hiçbiri olarak okunamayan bir dosya şu anda bunun yerine sunucu hatasıyla (500) reddedilebilir; böyle bir dosyayı değiştirmeden tekrar göndermeyin. Tek başına dosya uzantısı uyumluluğu kanıtlamaz.

Bu denetimlerin geçilmesi, sesin çözümlenebileceğini garanti etmez. Ses bir veya iki kanal olarak işlenir. İkiden fazla ses kanalı içeren bir dosya, çözümlenen sesi 2 saatten uzun olan bir dosya veya işleme sırasında başka bir nedenle çözümlenemeyen bir dosya, işlem sonunda failed durumuna geçer; hata kodu genellikle decode_failed olur ve iş ücretlendirilmez. Çok kanallı sesi göndermeden önce mono veya stereoya dönüştürün.

İsteğe bağlı dil ipucu, konuşulan dilin küçük harflerden oluşan iki veya üç harfli kodudur; örneğin en. İpucu vermemek için alanı atlayın; api.multi.tel boş dizeyi reddeder. İpucu, işlemeye yön verir ancak desteklenen diller listesine göre denetlenmez; bu nedenle konuşulan dil için geçerli bir kod kullanın.

Yazıya dökme işi gönderme

Şu başlıkla JSON gönderin: Content-Type: application/json; hedef: POST https://api.multi.tel/v3/speech_to_text. İstek gövdesi en fazla 35 MiB olabilir; bu sınır, en büyük dosyayı base64 kodlamasından sonra da kapsar. Daha büyük bir gövde 413 ile reddedilir.

Diğer tüm JSON özellikleri, idempotency_key dahil, 400 invalid_transcription_request ile reddedilir. Anahtarı başlık olarak gönderin.

İdempotans anahtarı

Her gönderimde 1 ila 190 karakterlik bir Idempotency-Key başlığı gerekir. ASCII harfleri, rakamlar, -, _, . ve : kullanın; başta veya sonda boşluk bırakmayın. Uyumluluk sunucusu çevredeki boşluk karakterlerini kırpar ve anahtarı bayt olarak ölçer; dolayısıyla diğer karakterler her sunucuda farklı sayılabilir. Eksik anahtar veya 191 ya da daha fazla karakter içeren anahtar 400 ile reddedilir.

Anahtarlar, her iki sunucuda ve hesabınızın tüm kimlik bilgileri genelinde hesabınızın ve konuşmayı metne dönüştürme hizmetinin kapsamındadır. Aynı anahtarı aynı dosya ve dille yeniden göndermek, işin durumu ne olursa olsun ve iş oluşturulduktan sonra işleme güncellenmiş olsa bile, ek ücret olmadan mevcut işi HTTP 200 ve duplicate: true ile döndürür. Bir anahtarı farklı dosya veya dille yeniden kullanmak 409 idempotency_conflict döndürür. Yeni bir anahtar, dosya aynı olsa bile yeni bir iş oluşturur ve işlem başarıyla tamamlanırsa ayrı ücret alınır.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

node -e 'process.stdout.write(JSON.stringify({audioBase64:require("node:fs").readFileSync("completed-call.mp3").toString("base64"),language:"en"}))' > completed-call.json

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-call-001" \
  --data-binary @completed-call.json \
  -o speech-job.json \
  https://api.multi.tel/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id'

Yeni bir iş aşağıda gösterilen alanlarla HTTP 202 döndürür; yinelenen istek ise şu bölümde açıklanan tam iş nesnesiyle HTTP 200 döndürür: Dökümü alma. UUID biçimindeki iş kimliğini data.id alanından okuyun. Yeni bir işin yanıtı şöyle görünür (kimlik ve değerler örnektir):

{
  "status": "success",
  "data": {
    "id": "3f6c1b2e-8a4d-4e7f-9c21-5b0d7e4a9f13",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "source": "api",
    "durationSeconds": 90.5,
    "billedSeconds": 91,
    "costUsd": "0.007583334",
    "pricePerMinuteUsd": "0.005"
  }
}

Bir iş kuyruktayken veya çalışırken durationSeconds, billedSeconds ve costUsd alanları, dosyanın meta verilerinden alınan tahminlerdir. Nihai ücret, çözümlenen süreyi kullanır.

Gönderim ayrıca, ön ödemeli bakiye işi diğer bekleyen işlerinizle birlikte karşılayamadığında 402 insufficient_balance, hesabınızda veya hizmette çok fazla bekleyen iş olduğunda 429 transcription_queue_full, dosya doğrulama kapasitesi dolduğunda 429 audio_validation_busy ve ücretli yazıya dökme devre dışıyken 503 paid_transcription_not_enabled döndürebilir. 429 ve 503 yanıtlarında daha sonra aynı anahtarla tekrar deneyin.

İş oluşturmadan tahmin alma

Aynı JSON gövdesini şuraya gönderin: POST https://api.multi.tel/v3/speech_to_text/estimate. İdempotans anahtarı gerekmez. Tahmin, dosyayı doğrular ve ölçer ancak yazıya dökmez, iş oluşturmaz, tutar ayırmaz, bakiyenizi denetlemez veya hesabınızı ücretlendirmez. language ipucu kabul edilir ancak tahmini etkilemez.

Başarılı bir tahmin, HTTP 200 ile şu alanları döndürür: estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd ve costUsd; bunlar şu nesnenin altındadır: data. Dosyanın meta verilerindeki süreyi kullanır; tamamlanan bir iş ise farklı olabilen çözümlenmiş süresine göre ücretlendirilir. Tahminlerde gönderimlerle aynı dosya denetimleri uygulanır. Yalnızca ücretli yazıya dökme etkinken kullanılabilirler (aksi durumda 503 paid_transcription_not_enabled). Dosya doğrulama kapasitesi dolduğunda 429 audio_validation_busy döndürebilirler; kısa bir süre bekleyip tekrar deneyin.

Dökümü alma

Şu uç noktayı düzenli olarak sorgulayın: GET /v3/speech_to_text/JOB_ID; şu kılavuzda açıklandığı gibi: iş akışı kılavuzu. İş nesnesi şu alanları içerir:

Dökümler ve bunların zaman damgaları, dil etiketleri ve kanal etiketleri otomatik üretilir ve doğru olmaları garanti edilmez. Her kalite bayrağını sonucu incelemek için bir neden olarak değerlendirin; önemli adları, sayıları ve taahhütleri özgün sesle karşılaştırın. Uzun sessizlikler ve çok kısık sesli kısımlar atlanır ve bunlar için bölüm üretilmez. Sonuçlar tek tek konuşmacıları tanımlamaz. Bir sonuçta channelCount değeri 2 ise her bölümün channel değeri A (ilk veya sol kanal) ya da B (ikinci veya sağ kanal) olur. Bu, konuşmacıları yalnızca her biri ayrı bir kanala kaydedildiyse ayırır. İki kanallı ses, kanal başına değil, geçen süresi üzerinden bir kez faturalandırılır. Mono sonuçlarda kanal etiketi bulunmaz.

api.multitel.net kullanımı

Uyumluluk uç noktası POST https://api.multitel.net/v3/speech_to_text, multipart/form-data biçimini, audio dosya parçası ve isteğe bağlı language alanıyla kabul eder; JSON audioBase64 yerine bu biçim kullanılır. Boş language değeri, ipucu verilmemiş olarak değerlendirilir. Aynı Idempotency-Key başlığını gönderin. Başlık yoksa bu sunucu ayrıca bir idempotency_key form alanını da kabul eder. source, free, billing_source, realtime veya stream adlı alanlar 400 unsupported_transcription_option ile reddedilir; diğer form alanları yok sayılır. Bu sunucu şu hataları da döndürür:

• 400 idempotency_key_required eksik veya çok uzun anahtar için.
• 400 audio_upload_required eksik yükleme veya tamamen alınamamış yükleme için.
• 400 invalid_language geçersiz dil için.
• 413 invalid_audio_size boş veya çok büyük dosya için.
• 400 invalid_job hatalı biçimdeki iş kimliği için.

Bu sunucunun konuşmayı metne dönüştürme hizmetinden gelen yanıtlar şu zarfı kullanır: {"status":{"code":HTTP_STATUS},"response":{...}}. Burada status bir nesnedir, dize değildir. Başarılı yanıtta response, birincil sunucudaki data ile aynı nesneyi içerir; dolayısıyla iş kimliği response.id alanındadır. Hata durumunda response.code hata kodunu içerir; mesaj veya istek kimliği bulunmaz. Kimlik doğrulama hataları (401), sunucunun genel oturum açma denetimi tarafından döndürülür ve farklı bir gövdeye sahip olabilir; bu nedenle ayrıştırmadan önce HTTP durumunu denetleyin. Sunucular arasında yükleme kodlamasını veya yanıt ayrıştırıcısını birbirinin yerine kullanmayın.

Bu sunucuda tahmin almak için aynı multipart alanlarını POST ile şuraya gönderin: /v3/speech_to_text/estimate. İdempotans anahtarı gerekmez ve tahmin response altında bulunur.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Idempotency-Key: speech-call-001" \
  -F "audio=@completed-call.mp3" -F "language=en" \
  -o speech-job.json \
  https://api.multitel.net/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).response.id'