Metin çeviri API’si

Bu API, metni kuyruğa alınan işler olarak çevirir; her işin tek bir hedef dili vardır. Metni 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. 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/translate önekiyle de kullanılabilir; bu önek şu önekin yerine geçer: /v3/translate. Şu sunucuda: api.multitel.net, şu yolları kullanın: /v3/translate.

Hizmet bilgileri yanıtı şu alanları bildirir: enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages ve ratesNanosPerCharacter. cpuLanguages, standart çeviri için kabul edilen temel dil kodlarını listeler. ratesNanosPerCharacter, her motor için kaynak kod noktası başına yapılandırılmış fiyatı, ABD dolarının milyarda biri cinsinden verir: 5000 değeri, milyon kod noktası başına $5 anlamına gelir. Yanıt, gelişmiş çevirinin şu anda kullanılabilir olup olmadığını bildirmez; kullanılamıyorsa gelişmiş çeviri tahmini 503 döndürür. Bu bilgileri sorgulamak ücretsizdir.

Metin çevirme

Şu başlıkla JSON gönderin: Content-Type: application/json; hedef: POST https://api.multi.tel/v3/translate. Her işin tek bir hedef dili vardır; bu nedenle her hedef için ayrı bir iş gönderin.

Yerel ayar kodları BCP 47 etiketleridir ve 2 ila 63 harf, rakam ve kısa çizgiden oluşur. Standart yazım biçimine dönüştürülürler; dolayısıyla en-us, en-US olarak kaydedilir. Geçersiz etiketler ve und, mul veya zxx, 400 invalid_translation_language döndürür. Standart çevirinin kullanılabilirliği temel dile göre denetlenir; nb ve nn, no olarak sayılır. fr-CA gibi bölgesel bir hedef kabul edilir ve kaydedilir; ancak standart çıktı temel dili izler ve bölgeyi yansıtması garanti edilmez.

Bu sunucuda istek gövdesini 128 KiB sınırı içinde tutun. ASCII dışındaki her karakteri bir \u dizisi olarak kaçışlamak yerine metni UTF-8 olarak gönderin; kaçışlamak, 20,000 karakterlik bir isteğin sınırı aşmasına neden olabilir.

Gövde yalnızca bu dört alanı kabul eder. Diğer tüm özellikler 400 invalid_translation_request ile reddedilir; buna idempotency_key, sahip kimlikleri, ücretsiz işleme bayrakları ve bölüm dizileri dahildir.

İdempotans ve yeniden kullanım

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. 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 çeviri hizmetinin kapsamındadır.

• Aynı anahtar, aynı metin, standart yazım biçimindeki diller ve motorla kullanıldığında, mevcut işi HTTP 200 ve duplicate: true ile ek ücret olmadan döndürür.
• Aynı anahtar farklı metin, diller veya motorla kullanıldığında 409 idempotency_conflict döndürür. İş oluşturulduktan sonra işleme sürümü değişmişse aynı anahtar yine 409 döndürür. Bu durumda yeniden göndermek yerine özgün işi kimliğiyle sorgulayın.
• Yeni bir anahtar, aynı metin, standart yazım biçimindeki diller ve motorla kullanıldığında, bu içeriğe ve güncel işleme sürümüne sahip bir iş kuyruktaysa, çalışıyorsa, tamamlanmışsa veya ödeme bekliyorsa mevcut işi HTTP 200 ve duplicate: true ile yeni bir işleme ücreti olmadan döndürür. Yeniden kullanılan iş ödeme bekliyorsa yine de ödenmesi gerekir. Başarısız işler yeniden kullanılmaz: yeni bir iş oluşturulur ve tamamlandığında ücretlendirilir.

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

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

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

Yeni bir iş HTTP 202 döndürür. Örnek metin 57 kod noktası içerir; dolayısıyla milyon kod noktası başına $5 fiyatla maliyeti $0.000285 olur. Kısaltılmış bir yanıt (kimlik örnektir):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

Gönderim ayrıca, ön ödemeli bakiye işi diğer bekleyen işlerinizle birlikte karşılayamadığında 402 insufficient_balance ve hesabınızda veya hizmette çok fazla bekleyen iş olduğunda 429 translation_queue_full döndürebilir. Şu durumlarda 503 döndürür:

• paid_translation_not_enabled ücretli çeviri devre dışıyken.
• translation_unavailable gelişmiş çeviri kullanılamıyorken yapılan gelişmiş çeviri isteğinde.
• translation_pricing_unavailable seçilen motor için yapılandırılmış bir fiyat yokken.

429 ve 503 yanıtlarında daha sonra aynı anahtarla tekrar deneyin.

Kaliteyi seçme

Uzun metin daha küçük parçalar halinde işlenir ve yeniden birleştirilir. Satır sonları ve boşluklar değişebilir; bir cümle işleme sınırını aşarken bağlamını kaybedebilir. Özgün metni saklayın ve birleştirilen sonucu inceleyin. Standart çeviri, bölgesel etiketin temel dilini kullanır; etiketin kabul edilip kaydedilmesi bölgeye özgü ifade kullanımını garanti etmez.

Standart çeviri CPU tabanlı işleyicilerde çalışır. Gelişmiş çeviri, metni yapılandırılmış harici yapay zekâ hizmetine gönderir. Çıktısının yine de incelenmesi gerekir; hizmet, bir motorun her dil çifti veya metin türü için daha doğru olduğunu garanti etmez.

Standart çeviri, kalitesi ve işleme süresi dil çiftine göre değişen bir taslaktır. Gelişmiş çeviri, bağlamın önemli olduğu metinler için tasarlanmıştır ancak önemli adlar, sayılar, olumsuz ifadeler ve taahhütler açısından yine de incelenmelidir. İki seçenek de özgün dökümde zaten bulunan hataları düzeltmez; bu nedenle karşılaştırmak için özgün metni saklayın.

Güncel kullanılabilirliği, standart çevirinin desteklediği dilleri ve yapılandırılmış fiyatları denetlemek için aynı API sunucusunda GET /v3/translate kullanın. Kaynak veya hedef temel dili cpuLanguages listesinde bulunmayan bir standart istek 422 translation_language_pair_unavailable döndürür. source_language verildiğinde ve hedefle aynı temel dile sahip olduğunda istek iş oluşturmak yerine 409 translation_same_language döndürür. Gelişmiş çeviri ayrıca etkinleştirilir; kullanılamadığı sürece gelişmiş çeviri gönderimleri ve tahminleri 503 döndürür.

Önce tahmin alın

Sunucu api.multi.tel üzerinde aynı JSON gövdesini şuraya gönderin: POST /v3/translate/estimate. İdempotans anahtarı gerekmez. Tahmin, 422 ve 409 denetimleri dahil aynı doğrulamayı uygular ancak iş oluşturmaz, metin çevirmez, tutar ayırmaz, bakiyenizi denetlemez veya hesabınızı ücretlendirmez. HTTP 200 ile şu alanları döndürür: estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd ve costUsd; bunlar şu nesnenin altındadır: data. Yukarıdaki örnekte costUsd, standart fiyatla 0.000285000 değerindedir. Gelişmiş çeviri kullanılamıyorken gelişmiş çeviri tahmini 503 service_unavailable döndürür. Tahminler o anda yapılandırılmış fiyatı kullanır. Bir işin fiyatı, iş oluşturulurken sabitlenir ve ücreti bu fiyat üzerinden hesaplanır.

Çeviriyi alma

Yeni bir gönderim HTTP 202, mevcut veya yeniden kullanılan iş HTTP 200 döndürür. data.id değerini saklayın ve ortak iş akışı kılavuzunu kullanın. İş nesnesi şu alanları içerir:

• id, status, engine, sourceLocale ve targetLocale.
• sourceCharacters, costUsd, costIsEstimate ve pricePerMillionCharactersUsd.
• progress ve createdAt.
• modelVersion, anlamı dışarıdan yorumlanamayan bir işleme sürümü dizesi.
• duplicate yeniden kullanılan işi döndüren yanıtlarda bulunur.
• failureCode başarısız işler için: translation_failed, translation_timeout, input_failed veya worker_lease_lost.

Başarısız bir işte costUsd sıfırdır.

Tamamlanmış bir işte data.result bulunur; şu alanları içerir: sourceLocale (kaynak dil verilmediyse boş), targetLocale, çevrilmiş text (bölüm metinleri satır sonlarıyla birleştirilir) ve segments. Bu API üzerinden gönderilen metinlerde segments, çevrilmiş text ve hedef language içeren tek bir kayıt barındırır. Ödeme bekleyen işlerin sonuçları ödeme yapılana kadar verilmez.

api.multitel.net kullanımı

Uyumluluk uç noktası POST https://api.multitel.net/v3/translate, aynı JSON alanlarını ve aynı Idempotency-Key başlığını kabul eder. Başlık yoksa JSON gövdesinde bir idempotency_key dizesi de kabul eder. Diğer tüm ek alanlar 400 unsupported_translation_option ile reddedilir. Bu sunucuda ham gövde en fazla 256,000 bayt olabilir; 20,000 kod noktasını aşan metin 413 translation_too_large döndürür; 400 döndürmez. Boş source_language atlanmış olarak değerlendirilir. 429 yanıtı Retry-After: 15 içerir. Bu sunucu şu hataları da döndürür:

• 400 json_body_required gövde eksik, geçersiz JSON veya JSON skaler değeri olduğunda. Bir JSON nesnesi gönderin.
• 400 invalid_translation_options şu alanlardan biri: text, target_language veya engine eksik, boş veya dize değilse ya da source_language dize değilse.
• 400 invalid_translation_text yalnızca boşluk karakterlerinden oluşan metin için.
• 400 invalid_translation_engine bilinmeyen motor için.
• 400 idempotency_key_required eksik, boş veya çok uzun anahtar ya da dize olmayan idempotency_key için.
• 400 invalid_job hatalı biçimdeki iş kimliği için.

Bu sunucunun çeviri hizmetinden gelen yanıtlar şu zarfı kullanır: {"status":{"code":HTTP_STATUS},"response":{...}}; burada status bir nesnedir. İş kimliğini response.id alanından, tamamlanmış sonucu ise response.result alanından okuyun. Hatalarda kod response.code alanına konur; 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. İşler birincil sunucuyla paylaşılır; ancak ayrıştırıcınızın zarfa uyması için sorgulama, ödeme ve kullanım işlemlerinde aynı sunucuyu kullanın. Bu sunucu aynı JSON alanlarını şu uç noktada da kabul eder: /v3/translate/estimate; idempotans anahtarı gerekmez ve tahmin response altında bulunur.