Konuşma ve çeviri işleri

Aşağıdaki SERVICE değerini şununla değiştirin: speech_to_text veya translate; JOB_ID değerini de döndürülen UUID ile değiştirin. Tüm işlemler hesabınıza ait kimlik bilgileri gerektirir (bkz. Kimlik doğrulama) ve işin sahibi olan hesapla sınırlıdır. Bir iş her iki API ana makinesinden de okunabilir, ancak her ana makine kendi zarf biçimini kullanır; bu nedenle tutarlı şekilde tek bir ana makine kullanın.

Şu ana makinede: api.multitel.net, kimlik doğrulama hataları (401) bu zarf uygulanmadan önce döndürülür ve farklı bir gövdeye sahip olabilir; bu nedenle ayrıştırmadan önce HTTP durum kodunu kontrol edin.

Kimlik doğrulama

Her istek hesabınıza ait kimlik bilgilerini taşımalıdır. İşler, idempotency anahtarları, limitler, kullanım ve ücretler, kimlik bilgilerinin sahibi olan hesaba aittir. Bunlar, isteği hangi kimlik bilgisi gönderirse göndersin, her iki ana makinede de o hesabın tüm kimlik bilgileri tarafından paylaşılır.

• HTTP Basic kimlik doğrulaması (Authorization: Basic, veya curl --user). Kabul edilen kimlik bilgileri şunlardır: parola türünde bir API hesabı, bir alt hesap veya hesabınızın oturum açma bilgileri. Bu amaca özel bir API hesabı kullanmanızı öneririz. Kullanıcı adı iki nokta üst üste içeremez; ne kullanıcı adı ne de parola boş olabilir.
• Bearer belirteci (Authorization: Bearer YOUR_TOKEN). Token türündeki API hesapları için kabul edilir. Token API hesaplarında IP kısıtlaması bulunmalıdır ve istekler izin verilen bir adresten gelmelidir. Her iki API ana makinesi de hesabın yapılandırılmış IPv4 adreslerini ve CIDR aralıklarını kabul eder. Token, Basic parolası olarak gönderilemez. Token'ınızın kullandığınız ana makinede çalıştığını doğrulayın.

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Bir API hesabı IP adresine göre kısıtlanmışsa istekleri izin verilen bir adresten gönderin. Eksik veya geçersiz kimlik bilgileri 401 döndürür. Şu ana makinede: api.multitel.net, geçerli olan ancak bu hizmetleri kullanamayan kimlik bilgileri (örneğin Basic olarak gönderilen bir token hesabının kimlik bilgileri) şunu döndürür: 403 unsupported_transcription_principal veya unsupported_translation_principal. Tek bir adresten api.multitel.net üzerinde tekrarlanan başarısız kimlik doğrulama denemeleri o adresin engellenmesine neden olabilir; bu nedenle yeniden denemeden önce kimlik bilgilerini düzeltin.

Tamamlanmayı yoklama

İstek gönderin: GET /v3/SERVICE/JOB_ID. En fazla 3 saniyede bir yoklama yapmanızı öneririz. Dış zarf isteği açıklar; işlemenin bitip bitmediğini belirlemek için iç işin status alanını inceleyin.

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

Şu ana makineyi kullanıyorsanız: api.multitel.net, HOST değişkenini https://api.multitel.net olarak ayarlayın ve .response.id alanını okuyun (şunun yerine: .data.id).

Belirsiz istekleri güvenle yeniden deneme

Bir gönderim zaman aşımına uğrarsa ya da 429 veya 5xx durum kodu döndürürse, aynı girdiyi aynı idempotency anahtarıyla yeniden gönderin. İki ana makineden herhangi birinden gelen yanıt, iş kabul edildikten sonra kaybolabilir veya bir hatayla değiştirilebilir; aynı anahtarla yeniden göndermek, iş mevcutsa o işi döndürür. Farklı girdiyle yeniden kullanılan bir anahtar şunu döndürür: 409 idempotency_conflict. Bazı hatalar her denemede tekrarlanır; örneğin ücretli bir hizmet devre dışıyken 503 veya okunamayan bir ses dosyası için 500. Bu nedenle birkaç denemeden sonra durun.

Anahtarı değiştirmenin etkisi hizmete göre farklılık gösterir.

• Konuşmadan metne dönüştürmede yeni bir anahtar, işleme başarıyla tamamlanırsa ayrıca ücretlendirilen yeni bir iş oluşturur. Orijinal anahtar, işleme güncellendikten sonra bile orijinal işi döndürmeye devam eder.
• Çeviride, aynı içeriğe sahip yeni bir anahtar; kuyrukta bekleyen, çalışan, tamamlanmış veya ödeme bekleyen eşleşen bir işi yeni bir ücret olmadan döndürür. Önceki iş başarısız olduysa veya işleme sürümü değiştiyse yeni iş oluşturur. İşleme sürümü değiştikten sonra orijinal anahtarla yapılan bir çeviri yeniden denemesi 409 döndürür; bu nedenle orijinal iş kimliğini saklayın ve işi doğrudan okuyun.

Bakiye ekledikten sonra sonucu serbest bırakma

Şu durumdaki bir iş için: awaiting_payment, bakiyeniz en az işin costUsd değerinin bir sonraki $0.00001'e yukarı yuvarlanmış tutarına ulaşacak şekilde bakiye ekleyin, ardından şunu gönderin: POST /v3/SERVICE/JOB_ID/settle. Borçlandırmalar $0.00001'lik tam adımlarla yapılır ve aynı hizmetin önceki işlerinden devreden kalanı da içerir; bu nedenle borçlandırılan tutar costUsd değerini $0.00001'den az bir farkla aşabilir. Şu ana makinede: api.multi.tel, JSON olarak {} veya boş bir gövde gönderin; gövdedeki herhangi bir özellik 400 ile reddedilir. api.multitel.net ise gövdeyi yok sayar. Ödeme tamamlama, transkripsiyonu veya çeviriyi yeniden çalıştırmadan kaydedilmiş sonucu serbest bırakır. Yanıt işi içerir; durumunun şu olduğunu kontrol edin: completed. Bakiye hâlâ yetersizse iş awaiting_payment durumunda kalır ve yanıt yine HTTP 200 olur.

Konuşmadan metne dönüştürmede, zaten tamamlanmış bir işin ödemesini tamamlamak işi şu değerle döndürür: duplicate: true, kuyrukta bekleyen, çalışan veya başarısız bir işin ödemesini tamamlamak ise şunu döndürür: 409 transcription_not_awaiting_payment. Çeviride, başka herhangi bir durumdaki işin ödemesini tamamlamak işi değiştirmeden döndürür. Ödeme tamamlama yalnızca ücretli işleme etkinken kullanılabilir (aksi hâlde 503). Ödeme bekleyen işler ayrılmış maliyet olarak sayılır; bu nedenle ön ödemeli hesaplarda, ödemeleri tamamlanana kadar yeni ücretli gönderimleri 402 ile engelleyebilir.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Kullanımı kontrol etme

Şunu kullanın: GET /v3/SERVICE/usage. İsteğe bağlı from ve to parametreleri UTC tarihleridir ve biçimi YYYY-MM-DD şeklindedir; her iki sınır tarihi de dahildir. Belirtilmezse from varsayılan olarak bugünden 30 gün öncesidir ve to varsayılan olarak bugündür (UTC). to şundan önce olamaz: from, ayrıca tarihler arasında en fazla 366 gün fark olabilir (en fazla 367 tarih). Geçersiz takvim tarihleri ya da ters veya daha uzun bir aralık 400 döndürür; şu ana makinedeki diğer sorgu parametreleri de aynı sonucu verir: api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

Yanıt şunları içerir: mode, currency (USD), from, to ve days, en yeniden eskiye sıralanmış bir liste.

• Konuşmadan metne kayıtları tarihe ve kaynağa göre gruplandırılır. Şunları içerirler: date, source (api, Hosted PBX kayıtları için ise hpbx kullanılır), files, audioSeconds, billedSeconds, accruedUsd ve debitedUsd.
• Çeviri kayıtları tarihe, kaynağa ve motora göre gruplandırılır. Şunları içerirler: date, source, engine, jobs, sourceCharacters, accruedUsd ve debitedUsd.

accruedUsd dokuz ondalık basamaklı kesin maliyettir; debitedUsd ise beş ondalık basamaklı borçlandırılan tutardır. Kullanım, her işin ücretinin kesinleştiği UTC tarihinde kaydedilir; bu nedenle kuyrukta bekleyen, çalışan, başarısız ve ödeme bekleyen işler görünmez.

Limitler

Her hesabın, Hosted PBX kayıt işleri dahil, toplamda en fazla 50 açık konuşmadan metne ve çeviri işi olabilir: kuyrukta bekleyen, çalışan veya ödeme bekleyen. Bu limite veya genel hizmet kapasitesine ulaşıldığında gönderimler şunu döndürür: 429 transcription_queue_full veya translation_queue_full. api.multi.tel ana makinesi ayrıca her istemci IP adresini, o ana makineye yapılan tüm isteklerde dakikada 300 istekle sınırlar. Bu limit, JSON hata zarfı yerine hız limiti başlıkları ve düz metin gövdesiyle 429 döndürür.

İstek hatalarını işleme

Birincil ana makinede hatalar, bir HTTP hata durum kodu ve şunları içeren bir JSON döndürür: status: "error", code, message ve requestId. Her yanıt ayrıca bir X-Request-ID başlığı taşır. Kendi değerinizi sağlayabilirsiniz; 128 karakterden uzun değerler kırpılır. Uyumluluk ana makinesi yalnızca hata kodunu şu alanda döndürür: response.code. Varsa istek kimliğini ve hata kodunu günlüğe kaydedin; ses, metin ve kimlik bilgilerini günlüklerin dışında tutun.

Yaygın durum kodları:

Her doğrulama hatasının tek bir durum kodu olduğunu varsaymak yerine döndürülen hata koduna göre hareket edin.

429 veya 503 için bekleyin ve artan bekleme süreleriyle (backoff) aynı gönderim anahtarını kullanarak yeniden deneyin; varsa Retry-After başlığına uyun. Geçersiz girdi veya kimlik bilgilerinde önce nedeni düzeltin. Önceki işler hâlâ kuyruktayken art arda yeni anahtarlarla gönderim yapmayın.