API dịch văn bản

API này dịch văn bản bằng tác vụ trong hàng đợi, mỗi tác vụ có một ngôn ngữ đích. Gửi văn bản, lưu ID tác vụ được trả về và truy vấn tác vụ cho đến khi xử lý xong. Gửi mọi yêu cầu qua HTTPS bằng thông tin xác thực của tài khoản: thông tin HTTP Basic như trong ví dụ hoặc mã thông báo API, theo hướng dẫn tại Xác thực. Giữ thông tin xác thực trên máy chủ của bạn.

Điểm cuối

Hai máy chủ API, https://api.multi.tel và máy chủ tương thích https://api.multitel.net, dùng chung tác vụ, khóa lũy đẳng, giới hạn và tính phí trong phạm vi tài khoản. Chúng khác nhau về cấu trúc bao ngoài của phản hồi, vì vậy hãy dùng nhất quán một máy chủ với bộ phân tích phù hợp.

Trên api.multi.tel, mọi đường dẫn cũng có thể dùng tiền tố /v1/translate thay cho /v3/translate. Trên api.multitel.net, hãy dùng các đường dẫn /v3/translate.

Phản hồi thông tin dịch vụ cung cấp enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages và ratesNanosPerCharacter. cpuLanguages liệt kê mã ngôn ngữ cơ sở được chấp nhận cho dịch tiêu chuẩn. ratesNanosPerCharacter cung cấp giá đã cấu hình cho mỗi điểm mã trong văn bản nguồn của từng bộ máy, tính theo phần tỷ đô la Mỹ: giá trị 5000 nghĩa là $5 cho mỗi triệu điểm mã. Phản hồi không cho biết dịch nâng cao hiện có khả dụng hay không; khi không khả dụng, ước tính nâng cao trả về 503. Việc đọc là miễn phí.

Dịch văn bản

Gửi JSON với Content-Type: application/json đến POST https://api.multi.tel/v3/translate. Mỗi tác vụ có một ngôn ngữ đích, nên hãy gửi tác vụ riêng cho từng đích.

Mã ngôn ngữ khu vực là thẻ BCP 47 gồm 2 đến 63 chữ cái, chữ số và dấu gạch nối. Chúng được chuyển về dạng chuẩn, nên en-us được ghi thành en-US. Thẻ không hợp lệ, và und, mul hoặc zxx, trả về 400 invalid_translation_language. Khả năng dùng dịch tiêu chuẩn được kiểm tra theo ngôn ngữ cơ sở; nb và nn được coi là no. Đích theo vùng như fr-CA được chấp nhận và ghi lại, nhưng đầu ra tiêu chuẩn theo ngôn ngữ cơ sở, không bảo đảm phản ánh cách dùng từ của vùng.

Giữ nội dung yêu cầu trong 128 KiB trên máy chủ này. Gửi văn bản dạng UTF-8 thay vì biểu diễn mọi ký tự ngoài ASCII bằng chuỗi thoát \u, vì cách đó có thể làm yêu cầu 20,000 ký tự vượt giới hạn.

Nội dung chỉ nhận bốn trường này. Mọi thuộc tính khác bị từ chối với 400 invalid_translation_request, kể cả idempotency_key, ID chủ sở hữu, cờ xử lý miễn phí và mảng các đoạn.

Tính lũy đẳng và tái sử dụng

Mỗi lần gửi đều cần tiêu đề Idempotency-Key dài từ 1 đến 190 ký tự. Dùng chữ cái ASCII, chữ số, -, _, . và :, không có khoảng trắng đầu hoặc cuối; thiếu khóa hoặc khóa dài từ 191 ký tự trở lên bị từ chối với 400. Khóa có phạm vi là tài khoản của bạn và dịch vụ dịch, trên cả hai máy chủ và mọi thông tin xác thực của tài khoản.

• Cùng khóa với cùng văn bản, ngôn ngữ ở dạng chuẩn và bộ máy sẽ trả về tác vụ hiện có với HTTP 200 và duplicate: true, không tính phí lần nữa.
• Cùng khóa với văn bản, ngôn ngữ hoặc bộ máy khác trả về 409 idempotency_conflict. Cùng khóa cũng trả về 409 nếu phiên bản xử lý đã thay đổi sau khi tạo tác vụ. Trong trường hợp đó, đọc tác vụ ban đầu bằng ID thay vì gửi lại.
• Khóa mới với cùng văn bản, ngôn ngữ ở dạng chuẩn và bộ máy sẽ trả về tác vụ hiện có với HTTP 200 và duplicate: true, không có phí xử lý mới, nếu tác vụ với nội dung đó và phiên bản xử lý hiện tại đang chờ, đang chạy, đã hoàn tất hoặc đang chờ thanh toán. Tác vụ tái sử dụng đang chờ thanh toán vẫn cần được thanh toán. Tác vụ thất bại không được tái sử dụng: tác vụ mới được tạo và tính phí khi hoàn tất.

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'

Tác vụ mới trả về HTTP 202. Văn bản ví dụ có 57 điểm mã, nên với mức $5 mỗi triệu điểm mã, chi phí là $0.000285. Phản hồi rút gọn (mã định danh chỉ là ví dụ):

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

Lần gửi cũng có thể trả về 402 insufficient_balance khi số dư trả trước không đủ chi trả tác vụ cùng các tác vụ chưa thanh toán khác, và 429 translation_queue_full khi tài khoản hoặc dịch vụ có quá nhiều tác vụ chưa hoàn tất. Trả về 503 trong các trường hợp sau:

• paid_translation_not_enabled khi dịch trả phí bị tắt.
• translation_unavailable cho yêu cầu nâng cao khi dịch nâng cao không khả dụng.
• translation_pricing_unavailable khi bộ máy đã chọn chưa được cấu hình mức giá.

Thử lại các phản hồi 429 và 503 sau bằng cùng khóa.

Chọn chất lượng

Văn bản dài được xử lý thành các phần nhỏ rồi ghép lại. Dấu xuống dòng và khoảng cách có thể thay đổi, và câu có thể mất ngữ cảnh khi nằm qua ranh giới xử lý. Giữ văn bản gốc và rà soát kết quả ghép. Dịch tiêu chuẩn dùng ngôn ngữ cơ sở của thẻ theo vùng; việc chấp nhận và ghi thẻ không bảo đảm dùng từ theo vùng.

Dịch tiêu chuẩn chạy trên tiến trình xử lý CPU. Dịch nâng cao gửi văn bản đến dịch vụ AI bên ngoài đã cấu hình. Đầu ra vẫn cần rà soát; dịch vụ không bảo đảm một bộ máy chính xác hơn cho mọi cặp ngôn ngữ hoặc loại văn bản.

Dịch tiêu chuẩn là bản nháp có chất lượng và thời gian xử lý tùy theo cặp ngôn ngữ. Dịch nâng cao dành cho văn bản cần ngữ cảnh, nhưng vẫn phải rà soát tên, số liệu, phủ định và cam kết quan trọng. Cả hai lựa chọn đều không sửa lỗi đã có trong bản chép lời gốc, nên hãy giữ bản gốc để đối chiếu.

Dùng GET /v3/translate trên cùng máy chủ API để kiểm tra khả năng cung cấp hiện tại, ngôn ngữ tiêu chuẩn được hỗ trợ và mức giá đã cấu hình. Yêu cầu tiêu chuẩn có ngôn ngữ cơ sở nguồn hoặc đích không nằm trong cpuLanguages trả về 422 translation_language_pair_unavailable. Khi source_language được cung cấp và có cùng ngôn ngữ cơ sở với đích, yêu cầu trả về 409 translation_same_language thay vì tạo tác vụ. Dịch nâng cao được bật riêng: khi không khả dụng, lượt gửi và ước tính nâng cao trả về 503.

Ước tính trước

Trên api.multi.tel, gửi cùng nội dung JSON đến POST /v3/translate/estimate. Không cần khóa lũy đẳng. Ước tính áp dụng cùng các bước xác thực, kể cả kiểm tra 422 và 409, nhưng không tạo tác vụ, dịch văn bản, giữ tiền, kiểm tra số dư hoặc tính phí tài khoản. Trả về HTTP 200 với estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd và costUsd nằm trong data. Với ví dụ trên, costUsd là 0.000285000 ở mức giá tiêu chuẩn. Khi dịch nâng cao không khả dụng, ước tính nâng cao trả về 503 service_unavailable. Ước tính dùng mức giá hiện được cấu hình. Mức giá của tác vụ được cố định khi tạo, và chi phí được tính theo mức đó.

Lấy bản dịch

Lượt gửi mới trả về HTTP 202, còn tác vụ hiện có hoặc tái sử dụng trả về HTTP 200. Giữ data.id và dùng quy trình tác vụ dùng chung. Đối tượng tác vụ chứa các trường sau:

• id, status, engine, sourceLocale và targetLocale.
• sourceCharacters, costUsd, costIsEstimate và pricePerMillionCharactersUsd.
• progress và createdAt.
• modelVersion, chuỗi phiên bản xử lý nội bộ, không dùng để diễn giải.
• duplicate trên phản hồi tái sử dụng.
• failureCode cho tác vụ thất bại: translation_failed, translation_timeout, input_failed hoặc worker_lease_lost.

Tác vụ thất bại có costUsd bằng không.

Tác vụ hoàn tất có data.result chứa sourceLocale (rỗng nếu không cung cấp ngôn ngữ nguồn), targetLocale, text đã dịch (văn bản các đoạn nối bằng dấu xuống dòng), và segments. Với văn bản gửi qua API này, segments chứa một mục với text đã dịch và language đích. Kết quả của tác vụ chờ thanh toán không được cung cấp cho đến khi thanh toán xong.

Dùng api.multitel.net

Điểm cuối tương thích POST https://api.multitel.net/v3/translate chấp nhận cùng các trường JSON và tiêu đề Idempotency-Key. Nếu không có tiêu đề, nó cũng chấp nhận chuỗi idempotency_key trong nội dung JSON. Mọi trường bổ sung khác bị từ chối với 400 unsupported_translation_option. Trên máy chủ này, nội dung thô có thể tối đa 256,000 byte, và văn bản hơn 20,000 điểm mã trả về 413 translation_too_large thay vì 400. source_language rỗng được coi là bỏ qua. Phản hồi 429 gồm Retry-After: 15. Máy chủ này cũng trả về các lỗi sau:

• 400 json_body_required khi thiếu nội dung, JSON không hợp lệ hoặc nội dung là giá trị vô hướng JSON. Gửi một đối tượng JSON.
• 400 invalid_translation_options khi text, target_language hoặc engine bị thiếu, rỗng hoặc không phải chuỗi, hoặc source_language không phải chuỗi.
• 400 invalid_translation_text khi văn bản chỉ chứa khoảng trắng.
• 400 invalid_translation_engine khi bộ máy không xác định.
• 400 idempotency_key_required khi thiếu khóa, khóa rỗng hoặc quá dài, hoặc idempotency_key không phải chuỗi.
• 400 invalid_job khi ID tác vụ sai định dạng.

Phản hồi từ dịch vụ dịch của máy chủ này dùng cấu trúc bao ngoài {"status":{"code":HTTP_STATUS},"response":{...}}, trong đó status là đối tượng. Đọc ID tác vụ từ response.id và kết quả hoàn tất từ response.result. Lỗi đặt mã trong response.code, không có thông điệp hoặc ID yêu cầu. Lỗi xác thực (401) do bước kiểm tra đăng nhập chung của máy chủ trả về và có thể có nội dung khác, vì vậy hãy kiểm tra trạng thái HTTP trước khi phân tích. Tác vụ được dùng chung với máy chủ chính, nhưng hãy dùng cùng máy chủ khi thăm dò, thanh toán và truy vấn mức sử dụng để bộ phân tích khớp với cấu trúc bao ngoài. Máy chủ này cũng nhận cùng các trường JSON tại /v3/translate/estimate mà không cần khóa lũy đẳng; ước tính nằm trong response.