Dịch vụ AI

Cách tích hợp dịch bằng AI

Gửi văn bản và nhận về bản dịch giữa 2 trong số 100 ngôn ngữ được hỗ trợ, tính phí theo lượng văn bản bạn gửi.

Nội dung request

Gửi phần thân request dạng JSON:

Trường	Ý nghĩa
`text`	text là bắt buộc. Tối đa 10.000 ký tự (giao diện test trên trang riêng giới hạn chặt hơn, ở mức 1.000).
`sourceLanguage`	sourceLanguage là tùy chọn, một trong 100 mã ngôn ngữ bên dưới. Nếu bỏ trống, mặc định là "en" chứ không tự động phát hiện.
`targetLanguage`	targetLanguage là bắt buộc, một trong 100 mã ngôn ngữ bên dưới.

Ví dụ

curl -X POST https://core.roammoon.com/v1/ai/translation/translate \
  -H "X-API-Key: rm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, world!", "sourceLanguage": "en", "targetLanguage": "vi"}'

Kết quả trả về

Trả về văn bản đã dịch cùng với số credit thực sự bị trừ:

JSON

{
  "translatedText": "Xin chào, thế giới!",
  "sourceLanguage": "en",
  "targetLanguage": "vi",
  "characterCount": 13,
  "creditsCharged": 1
}

Các trường quan trọng

Trường	Ý nghĩa
`translatedText`	Văn bản đã được dịch.
`characterCount`	Độ dài văn bản bạn đã gửi.
`creditsCharged`	Chi phí thực tế của lệnh gọi này: ceil(characterCount / 100), tối thiểu 1.

Tính phí

Khác với các dịch vụ AI khác trên nền tảng, dịch vụ này tính phí theo dung lượng thay vì mức cố định mỗi lần gọi: 1 credit cho mỗi 100 ký tự văn bản đầu vào, làm tròn lên, tối thiểu 1 credit. Một request 10.000 ký tự tốn tối đa 100 credit. Chỉ trừ credit khi dịch thành công, mọi trường hợp thất bại đều được hoàn lại.

Chính sách tính phí là charge-on-success: credit được giữ chỗ khi tiếp nhận request và chỉ thực sự trừ khi xử lý thành công. Thất bại thì hoàn lại.

Ngôn ngữ được hỗ trợ

Cả sourceLanguage và targetLanguage đều chấp nhận bất kỳ mã nào trong 100 mã sau.

Ngôn ngữ	Mã	Ngôn ngữ	Mã
Afrikaans	`af`	Ganda	`lg`
Amharic	`am`	Lingala	`ln`
Arabic	`ar`	Lao	`lo`
Asturian	`ast`	Lithuanian	`lt`
Azerbaijani	`az`	Latvian	`lv`
Bashkir	`ba`	Malagasy	`mg`
Belarusian	`be`	Macedonian	`mk`
Bulgarian	`bg`	Malayalam	`ml`
Bengali	`bn`	Mongolian	`mn`
Breton	`br`	Marathi	`mr`
Bosnian	`bs`	Malay	`ms`
Catalan	`ca`	Burmese	`my`
Cebuano	`ceb`	Nepali	`ne`
Czech	`cs`	Dutch	`nl`
Welsh	`cy`	Norwegian	`no`
Danish	`da`	Northern Sotho	`ns`
German	`de`	Occitan	`oc`
Greek	`el`	Oriya	`or`
English	`en`	Punjabi	`pa`
Spanish	`es`	Polish	`pl`
Estonian	`et`	Pashto	`ps`
Persian	`fa`	Portuguese	`pt`
Fulah	`ff`	Romanian	`ro`
Finnish	`fi`	Russian	`ru`
French	`fr`	Sindhi	`sd`
Western Frisian	`fy`	Sinhala	`si`
Irish	`ga`	Slovak	`sk`
Scottish Gaelic	`gd`	Slovenian	`sl`
Galician	`gl`	Somali	`so`
Gujarati	`gu`	Albanian	`sq`
Hausa	`ha`	Serbian	`sr`
Hebrew	`he`	Swati	`ss`
Hindi	`hi`	Sundanese	`su`
Croatian	`hr`	Swedish	`sv`
Haitian Creole	`ht`	Swahili	`sw`
Hungarian	`hu`	Tamil	`ta`
Armenian	`hy`	Thai	`th`
Indonesian	`id`	Tagalog	`tl`
Igbo	`ig`	Tswana	`tn`
Iloko	`ilo`	Turkish	`tr`
Icelandic	`is`	Ukrainian	`uk`
Italian	`it`	Urdu	`ur`
Japanese	`ja`	Uzbek	`uz`
Javanese	`jv`	Vietnamese	`vi`
Georgian	`ka`	Wolof	`wo`
Kazakh	`kk`	Xhosa	`xh`
Khmer	`km`	Yiddish	`yi`
Kannada	`kn`	Yoruba	`yo`
Korean	`ko`	Chinese	`zh`
Luxembourgish	`lb`	Zulu	`zu`

Mẹo để có kết quả tốt

Đặt sourceLanguage rõ ràng bất cứ khi nào văn bản của bạn không phải tiếng Anh. Để trống không có nghĩa là tự phát hiện, nó mặc định là tiếng Anh.
Câu ngắn, đúng ngữ pháp dịch đáng tin cậy hơn đoạn văn dài lẫn nhiều ngôn ngữ, tiếng lóng, hoặc định dạng phức tạp.
Đây là dịch máy, không phải người kiểm duyệt. Với nội dung xuất bản, pháp lý, hoặc liên quan an toàn, hãy nhờ người thông thạo ngôn ngữ đó kiểm tra lại trước khi dùng.

Lỗi

Mọi lỗi đều dùng chung một cấu trúc. Hãy xử lý theo trường code, không phải theo message, vì message có thể thay đổi.

JSON

{
  "error": {
    "code": "TEXT_TOO_LONG",
    "message": "The \"text\" field must be 10000 characters or fewer."
  }
}

HTTP	Mã lỗi	Nên làm gì
401	`API_KEY_REQUIRED`	Thiếu header X-API-Key.
401	`API_KEY_INVALID`	Key sai, đã bị vô hiệu hóa hoặc hết hạn. Kiểm tra lại hoặc tạo key mới.
403	`API_KEY_FORBIDDEN`	Key không có quyền dùng dịch vụ này.
400	`INVALID_TRANSLATION_REQUEST`	Trường "text" bị thiếu hoặc rỗng. Không bị trừ credit.
400	`TEXT_TOO_LONG`	Văn bản vượt quá 10.000 ký tự. Hãy rút ngắn hoặc chia thành nhiều lệnh gọi.
400	`UNSUPPORTED_LANGUAGE`	sourceLanguage hoặc targetLanguage không nằm trong danh sách mã được hỗ trợ.
402	`CREDIT_LIMIT_EXCEEDED`	Hết credit trong chu kỳ. Nâng gói hoặc chờ sang chu kỳ mới.
415	`JSON_BODY_REQUIRED`	Content-Type phải là application/json.
429	`RATE_LIMIT_EXCEEDED`	Vượt giới hạn request mỗi phút.
502	`TRANSLATION_UPSTREAM_ERROR`	Mô hình dịch không xử lý được request. Có thể thử lại.

Thử lại an toàn

502 có thể thử lại, dùng exponential backoff. Các lỗi khác trả về cùng kết quả khi thử lại. Chỉ lần dịch thành công mới bị trừ phí, nên thử lại sau khi thất bại không tốn thêm gì. Ngoại lệ là timeout mạng: nếu lần gọi đầu thực ra đã thành công, lần thử lại sẽ tính phí như một lệnh gọi thứ hai.

Tiếp theo: Tham chiếu API →