API terjemahan teks

API ini menerjemahkan teks sebagai tugas dalam antrean, satu bahasa target per tugas. Kirim teks, simpan ID tugas yang dikembalikan, dan ambil informasi tugas hingga pemrosesan selesai. Kirim setiap permintaan melalui HTTPS dengan kredensial akun Anda, baik kredensial HTTP Basic seperti dalam contoh maupun token API, sebagaimana dijelaskan di Autentikasi. Simpan kredensial di server Anda.

Endpoint

Dua host API, https://api.multi.tel dan host kompatibilitas https://api.multitel.net, berbagi tugas, kunci idempotensi, batas, dan penagihan yang sama dalam cakupan akun. Keduanya berbeda dalam struktur pembungkus respons, jadi gunakan satu host secara konsisten dengan parser yang sesuai.

Pada api.multi.tel, setiap jalur juga tersedia dengan prefiks /v1/translate sebagai pengganti /v3/translate. Pada api.multitel.net, gunakan jalur /v3/translate.

Respons informasi layanan melaporkan enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages dan ratesNanosPerCharacter. cpuLanguages mencantumkan kode bahasa dasar yang diterima untuk terjemahan standar. ratesNanosPerCharacter memberikan harga yang dikonfigurasi per titik kode sumber untuk setiap mesin, dalam sepermiliar dolar AS: nilai 5000 berarti $5 per satu juta titik kode. Respons tidak melaporkan apakah terjemahan tingkat lanjut saat ini tersedia; estimasi tingkat lanjut mengembalikan 503 jika tidak tersedia. Pembacaan ini gratis.

Terjemahkan teks

Kirim JSON dengan Content-Type: application/json ke POST https://api.multi.tel/v3/translate. Setiap tugas memiliki satu bahasa target, jadi kirim tugas terpisah untuk setiap target.

Kode lokal adalah tag BCP 47 yang terdiri dari 2 hingga 63 huruf, angka, dan tanda hubung. Kode diubah ke bentuk kanonis, sehingga en-us dicatat sebagai en-US. Tag yang tidak valid, serta und, mul atau zxx, mengembalikan 400 invalid_translation_language. Ketersediaan standar diperiksa berdasarkan bahasa dasar, dan nb dan nn dihitung sebagai no. Target regional seperti fr-CA diterima dan dicatat, tetapi hasil standar mengikuti bahasa dasar dan tidak dijamin mencerminkan wilayah tersebut.

Jaga isi permintaan tetap dalam 128 KiB pada host ini. Kirim teks sebagai UTF-8 alih-alih melakukan escape pada setiap karakter non-ASCII menjadi urutan \u, yang dapat membuat permintaan 20,000 karakter melewati batas.

Isi hanya menerima empat kolom ini. Properti lain apa pun ditolak dengan 400 invalid_translation_request, termasuk idempotency_key, ID pemilik, penanda pemrosesan gratis, dan array segmen.

Idempotensi dan penggunaan ulang

Setiap pengiriman memerlukan header Idempotency-Key sepanjang 1 hingga 190 karakter. Gunakan huruf ASCII, angka, -, _, . dan :, tanpa spasi di awal atau akhir; kunci yang tidak ada atau panjangnya 191 karakter atau lebih ditolak dengan 400. Kunci berlaku dalam cakupan akun Anda dan layanan terjemahan, di kedua host dan semua kredensial akun Anda.

• Kunci yang sama dengan teks, bahasa kanonis, dan mesin yang sama mengembalikan tugas yang sudah ada dengan HTTP 200 dan duplicate: true, tanpa biaya tambahan.
• Kunci yang sama dengan teks, bahasa, atau mesin berbeda mengembalikan 409 idempotency_conflict. Kunci yang sama juga mengembalikan 409 jika versi pemrosesan berubah sejak tugasnya dibuat. Dalam kasus itu, baca tugas asli berdasarkan ID-nya, bukan mengirim ulang.
• Kunci baru dengan teks, bahasa kanonis, dan mesin yang sama mengembalikan tugas yang sudah ada dengan HTTP 200 dan duplicate: true, tanpa biaya pemrosesan baru, jika tugas dengan konten tersebut dan versi pemrosesan saat ini berada dalam antrean, berjalan, selesai, atau menunggu pembayaran. Tugas yang digunakan ulang dan menunggu pembayaran tetap memerlukan penyelesaian pembayaran. Tugas gagal tidak digunakan ulang: tugas baru dibuat dan dikenai biaya ketika selesai.

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'

Tugas baru mengembalikan HTTP 202. Teks contoh memiliki 57 titik kode, sehingga dengan tarif $5 per satu juta titik kode biayanya $0.000285. Respons yang diringkas (pengenalnya adalah contoh):

{
  "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
  }
}

Pengiriman juga dapat mengembalikan 402 insufficient_balance ketika saldo prabayar tidak cukup untuk menanggung tugas tersebut beserta tugas lain yang belum selesai, dan 429 translation_queue_full ketika akun Anda atau layanan memiliki terlalu banyak tugas yang belum selesai. Respons 503 dikembalikan dalam kasus berikut:

• paid_translation_not_enabled saat terjemahan berbayar dinonaktifkan.
• translation_unavailable untuk permintaan tingkat lanjut saat terjemahan tingkat lanjut tidak tersedia.
• translation_pricing_unavailable saat mesin yang dipilih tidak memiliki tarif yang dikonfigurasi.

Ulangi respons 429 dan 503 nanti dengan kunci yang sama.

Pilih kualitas

Teks panjang diproses dalam bagian-bagian kecil dan digabungkan kembali. Pergantian baris dan spasi dapat berubah, dan kalimat dapat kehilangan konteks di batas pemrosesan. Simpan teks asli dan tinjau hasil yang digabungkan. Terjemahan standar menggunakan bahasa dasar dari tag regional; penerimaan dan pencatatan tag tidak menjamin penggunaan kata regional.

Terjemahan standar berjalan pada worker CPU. Terjemahan tingkat lanjut mengirim teks ke layanan AI eksternal yang dikonfigurasi. Hasilnya tetap perlu ditinjau; layanan tidak menjamin bahwa satu mesin lebih akurat untuk setiap pasangan bahasa atau jenis teks.

Terjemahan standar adalah draf yang kualitas dan waktu pemrosesannya bervariasi menurut pasangan bahasa. Terjemahan tingkat lanjut ditujukan untuk teks yang memerlukan konteks, tetapi tetap perlu ditinjau untuk nama, angka, negasi, dan komitmen penting. Tidak satu pun opsi memperbaiki kesalahan yang sudah ada dalam transkrip asli, jadi simpan teks asli untuk perbandingan.

Gunakan GET /v3/translate pada host API yang sama untuk memeriksa ketersediaan saat ini, bahasa standar yang didukung, dan tarif yang dikonfigurasi. Permintaan standar yang bahasa dasar sumber atau targetnya tidak tercantum di cpuLanguages mengembalikan 422 translation_language_pair_unavailable. Ketika source_language diberikan dan memiliki bahasa dasar yang sama dengan target, permintaan mengembalikan 409 translation_same_language alih-alih membuat tugas. Terjemahan tingkat lanjut diaktifkan secara terpisah: saat tidak tersedia, pengiriman dan estimasi tingkat lanjut mengembalikan 503.

Buat estimasi terlebih dahulu

Pada api.multi.tel, kirim isi JSON yang sama ke POST /v3/translate/estimate. Kunci idempotensi tidak diperlukan. Estimasi menerapkan validasi yang sama, termasuk pemeriksaan 422 dan 409, tetapi tidak membuat tugas, menerjemahkan teks, mencadangkan dana, memeriksa saldo, atau membebankan biaya ke akun Anda. Estimasi mengembalikan HTTP 200 dengan estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd dan costUsd di dalam data. Untuk contoh di atas, costUsd bernilai 0.000285000 pada tarif standar. Saat terjemahan tingkat lanjut tidak tersedia, estimasi tingkat lanjut mengembalikan 503 service_unavailable. Estimasi menggunakan tarif yang saat ini dikonfigurasi. Tarif tugas ditetapkan saat tugas dibuat, dan biayanya menggunakan tarif tersebut.

Ambil terjemahan

Pengiriman baru mengembalikan HTTP 202, dan tugas yang sudah ada atau digunakan ulang mengembalikan HTTP 200. Simpan data.id dan gunakan alur tugas bersama. Objek tugas berisi kolom berikut:

• id, status, engine, sourceLocale dan targetLocale.
• sourceCharacters, costUsd, costIsEstimate dan pricePerMillionCharactersUsd.
• progress dan createdAt.
• modelVersion, string versi pemrosesan yang maknanya tidak dijabarkan.
• duplicate pada respons penggunaan ulang.
• failureCode untuk tugas gagal: translation_failed, translation_timeout, input_failed atau worker_lease_lost.

Tugas gagal menampilkan costUsd bernilai nol.

Tugas yang selesai memiliki data.result dengan sourceLocale (kosong jika bahasa sumber tidak diberikan), targetLocale, hasil terjemahan text (teks segmen digabungkan dengan pergantian baris), dan segments. Untuk teks yang dikirim melalui API ini, segments berisi satu entri dengan hasil terjemahan text dan language target. Hasil tugas yang menunggu pembayaran ditahan hingga pembayaran diselesaikan.

Menggunakan api.multitel.net

Endpoint kompatibilitas POST https://api.multitel.net/v3/translate menerima kolom JSON yang sama dan header Idempotency-Key yang sama. Jika header tidak ada, host ini juga menerima string idempotency_key dalam isi JSON. Kolom tambahan lainnya ditolak dengan 400 unsupported_translation_option. Pada host ini, isi mentah dapat mencapai 256,000 byte, dan teks di atas 20,000 titik kode mengembalikan 413 translation_too_large alih-alih 400. Nilai source_language yang kosong dianggap tidak disertakan. Respons 429 menyertakan Retry-After: 15. Host ini juga mengembalikan kesalahan berikut:

• 400 json_body_required ketika isi tidak ada, JSON tidak valid, atau berupa skalar JSON. Kirim objek JSON.
• 400 invalid_translation_options ketika text, target_language atau engine tidak ada, kosong, atau bukan string, atau source_language bukan string.
• 400 invalid_translation_text untuk teks yang hanya berisi whitespace.
• 400 invalid_translation_engine untuk mesin yang tidak dikenal.
• 400 idempotency_key_required untuk kunci yang tidak ada, kosong, terlalu panjang, atau idempotency_key yang bukan string.
• 400 invalid_job untuk ID tugas yang formatnya salah.

Respons layanan terjemahan dari host ini menggunakan struktur pembungkus {"status":{"code":HTTP_STATUS},"response":{...}}, dengan status berupa objek. Baca ID tugas dari response.id dan hasil yang selesai dari response.result. Kesalahan menempatkan kode di response.code, tanpa pesan atau ID permintaan. Kegagalan autentikasi (401) dikembalikan oleh pemeriksaan masuk umum host dan dapat memiliki isi berbeda, jadi periksa status HTTP sebelum melakukan parsing. Tugas dibagikan dengan host utama, tetapi gunakan host yang sama untuk polling, penyelesaian pembayaran, dan penggunaan agar parser Anda sesuai dengan struktur pembungkus. Host ini juga menerima kolom JSON yang sama di /v3/translate/estimate tanpa kunci idempotensi, dan estimasinya berada di dalam response.