Bắt đầu nhanh
- Đăng nhập và tạo khóa API. Sao chép mục .env của mục đó vào tệp .env riêng tư bên cạnh ví dụ. Bản dịch API sử dụng tín dụng trong tài khoản, bao gồm tín dụng đăng ký đủ điều kiện; hạn mức sử dụng website hằng ngày không áp dụng. Không bao giờ đưa khóa vào kho mã nguồn hoặc mã trình duyệt công khai.
- Tải ví dụ Node.js xuống. Dùng Node.js 22 trở lên; không cần cài gói. Lưu một tài liệu văn bản UTF-8 ngắn dưới tên input.txt trong cùng thư mục. Ví dụ này hỗ trợ tối đa 16.000 ký tự; tài liệu lớn hơn sẽ dùng nhiều đoạn thông qua API bên dưới.
- Chạy lệnh đầu tiên để xem báo giá mà không dùng tín dụng. Xem lại báo giá, rồi chạy lệnh thứ hai để dịch sang tiếng Tây Ban Nha và lưu thành translated.txt. Thay đổi ngôn ngữ và đường dẫn nếu cần.
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt
node --env-file=.env translate-text.mjs input.txt Spanish translated.txt --startVí dụ này sẽ thăm dò trạng thái cho đến khi sẵn sàng và không bao giờ ghi đè đầu ra hiện có. Giữ tệp kiểm tra .translation.json của ví dụ và chạy lại cùng lệnh sau khi bị gián đoạn: tệp sẽ khôi phục tác vụ hiện có và bản tải xuống mà không tính thêm phí. Tệp kiểm tra không chứa nội dung tài liệu hoặc khóa API. Hết thời gian chờ không làm hủy quá trình xử lý.
API dịch nhận văn bản đã trích xuất và trả về các đoạn đã dịch. Bản sao lưu riêng tư tùy chọn cho phép khôi phục tài liệu trong vòng 24 giờ sau khi hoàn tất. Hãy tạo lại tài liệu hoàn chỉnh trong ứng dụng của bạn.
Hoặc sao chép https://document-translator.com/api/ và gửi cho tác nhân AI của bạn để được hướng dẫn bắt đầu.
Tạo quy trình dịch tài liệu
Trích xuất văn bản bằng các ID phân đoạn ổn định trong ứng dụng của bạn. Gửi dữ liệu tải lên như bên dưới, sau đó dùng từng ID được trả về để đưa bản dịch vào lại tài liệu.
Tạo báo giá
POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json
{
"version": "document-ir/13",
"format": "txt",
"fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
"sourceLanguage": "auto",
"targetLanguage": "Spanish",
"segments": [
{
"id": "s0",
"text": "Hello, world."
}
]
}Phản hồi bao gồm ID báo giá, số từ trong tài liệu nguồn, chi phí tín dụng chính xác và thời hạn hết hiệu lực. Báo giá có hiệu lực trong mười phút. Yêu cầu báo giá không giữ chỗ tín dụng hoặc lưu nội dung tài liệu.
Theo mặc định, báo giá sử dụng chế độ đầu ra nghiêm ngặt. Thêm output=best-effort-v1 vào URL báo giá để cho phép kết quả một phần. Kết quả sẵn sàng có thông tin về kết quả và các vấn đề; hãy kiểm tra trước khi sử dụng. Chính sách được cố định theo báo giá.
POST /api/v1/quotes?output=best-effort-v1Bắt đầu dịch
POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json
{
"quoteId": "<quote id>",
"idempotencyKey": "my-document-0001",
"payload": {
"version": "document-ir/13",
"format": "txt",
"fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
"sourceLanguage": "auto",
"targetLanguage": "Spanish",
"segments": [
{
"id": "s0",
"text": "Hello, world."
}
]
}
}Khi bắt đầu, hãy gửi lại dữ liệu đã dùng để báo giá. Máy chủ xác minh chủ sở hữu và mã băm chuẩn hóa trước khi lưu văn bản hoặc giữ tín dụng. Thứ tự khóa trong đối tượng JSON không quan trọng; nếu thay đổi văn bản, thứ tự phân đoạn, định dạng, dấu vân tay hoặc ngôn ngữ, bạn cần tạo báo giá mới.
Đọc kết quả đã dịch
GET /api/v1/translations/JOB_ID/result
Authorization: Bearer doctr_...
{
"version": "document-ir/13",
"jobId": "<job id>",
"fingerprint": "f8c3bf62a9aa3e6fc1619c250e48abe7519373d3edf41be62eb5dc45199af2ef",
"targetLanguage": "Spanish",
"segments": [
{
"id": "s0",
"text": "Hola, mundo."
}
],
"mock": false
}Dùng ID phân đoạn để dựng lại tệp; điểm cuối kết quả trả về JSON, không phải tài liệu hoàn chỉnh. Giữ khoảng trắng, liên kết, kiểu định dạng và các cấu trúc không cần dịch khác trong ứng dụng của bạn. Mỗi phân đoạn cần có ID duy nhất dài từ 1–48 ký tự, chỉ gồm a–z, 0–9, dấu gạch dưới hoặc dấu gạch nối. Văn bản mỗi phân đoạn tối đa 16,000 đơn vị mã UTF-16. Dấu vân tay là mã SHA-256 chữ thường của các byte trong tệp gốc.
Trang web phân tích và dựng lại tài liệu. Ứng dụng dùng API cung cấp văn bản đã trích xuất và tự dựng lại tệp. Tính năng nhận dạng ký tự (OCR) trong trình duyệt hỗ trợ bản quét rõ nét bằng sáu ngôn ngữ. Xem phần câu hỏi thường gặp trên trang chủ. Bố cục phức tạp có thể cần thêm trang hoặc một bản thay thế dễ đọc.
Một yêu cầu báo giá bằng cURL
Lưu JSON báo giá ở trên thành payload.json và đặt DOCUMENT_TRANSLATOR_API_KEY trong shell. Lệnh này chỉ yêu cầu báo giá. Để bắt đầu, gửi JSON bắt đầu cùng ID báo giá được trả về và dữ liệu yêu cầu giống hệt đến endpoint translations.
curl https://document-translator.com/api/v1/quotes \
-H "Authorization: Bearer $DOCUMENT_TRANSLATOR_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @payload.jsonTrong PowerShell, hãy dùng curl.exe và $env:DOCUMENT_TRANSLATOR_API_KEY; viết lệnh trên một dòng thay vì dùng dấu gạch chéo ngược để xuống dòng như minh họa ở trên.
Tín dụng dịch thuật và khóa API
Mỗi tài liệu API sẽ giữ trước một tín dụng tài khoản trong phạm vi giới hạn. Tác vụ nghiêm ngặt chỉ tính phí khi được xác thực và sẵn sàng; các tác vụ chưa hoàn tất bị lỗi hoặc hủy sẽ giải phóng khoản giữ trước. Với kết quả theo khả năng tốt nhất, các thiếu sót nhỏ có thể vẫn sử dụng tín dụng đã thỏa thuận, còn thiếu sót lớn hoặc lỗi nghiêm trọng sẽ giải phóng khoản đó. Hãy đọc outcome.creditOutcome và outcome.completion thay vì cho rằng mọi kết quả sẵn sàng đều đã bị tính phí.
Tạo tối đa năm khóa API đang hoạt động cho mỗi tài khoản. Khóa chỉ hiển thị một lần, được lưu dưới dạng mã băm và có thể thu hồi trong mục Tài khoản. Khóa đang hoạt động có thể truy cập các bản dịch đã thanh toán của tài khoản đó, bao gồm cả những tác vụ được tạo bằng khóa khác trên cùng tài khoản. Khóa không cho phép đăng nhập hoặc thanh toán.
Thử lại và yêu cầu bị gián đoạn
GET /api/v1/translations?requestKey=IDEMPOTENCY_KEY"eId=QUOTE_ID
DELETE /api/v1/translations?requestKey=IDEMPOTENCY_KEY"eId=QUOTE_IDSau khi yêu cầu bắt đầu gặp sự cố không rõ kết quả, hãy dùng lại cùng ID báo giá, dữ liệu yêu cầu và khóa idempotency. Các lần thử lại giống hệt sẽ trả về tác vụ hiện có mà không tính phí thêm. Nếu dữ liệu yêu cầu thay đổi hoặc dùng lại khóa cho báo giá khác, hệ thống sẽ trả về lỗi 409. Thông tin tác vụ và idempotency được lưu trong bảy ngày sau khi tác vụ kết thúc.
Có thể thử lại công việc thất bại nhưng có thể tiếp tục, miễn là văn bản nguồn vẫn còn. Lần thử lại giữ nguyên ID công việc và sử dụng lại các phần đã hoàn tất. Mỗi công việc được xử lý tối đa ba lần. Nếu tải xuống thất bại, bạn có thể thử lại điểm cuối kết quả mà không cần bắt đầu bản dịch khác.
Thăm dò trạng thái và tải xuống
GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_IDTrạng thái hàng loạt chấp nhận tối đa 100 ID và trả về { jobs: [...] }, chỉ gồm các tác vụ được phép truy cập và chưa bị xóa. Khi đang xử lý, hãy kiểm tra khoảng năm giây một lần; khi đang xếp hàng, khoảng mười lăm giây một lần. Luân phiên các lô một cách công bằng khi khôi phục hơn 100 tác vụ. Tạm dừng kiểm tra trong các thẻ đang ẩn và dừng khi tác vụ ở trạng thái kết thúc hoặc gặp lỗi cấp quyền vĩnh viễn.
Khi trạng thái là sẵn sàng, hãy lấy kết quả bằng cùng thông tin xác thực tài khoản. Kết quả chứa ánh xạ các phân đoạn đã dịch để bạn dựng lại tài liệu trên thiết bị của mình. Có thể truy cập kết quả trong 24 giờ sau khi hoàn tất; đầu vào không thành công sẽ hết hạn một giờ sau khi tạo. Kết quả hết hạn trả về 410. Tác vụ đã xóa hoặc không thể truy cập trả về 404.
queued → processing → ready
↘ failed / cancelled / expired
{"jobs":[{"id":"<job id>","state":"processing","completedChunks":1,"totalChunks":2}]}Lưu tệp đã hoàn tất bằng PUT với nội dung nhị phân, Content-Length và Content-Type khớp nhau. Các phần mở rộng được hỗ trợ gồm docx, pptx, xlsx, pdf, txt và md; mỗi định dạng được lưu thành một tệp riêng, với giới hạn đầu ra 50 MB. Lưu lại tệp đã lưu thành công sẽ giữ nguyên tệp hiện có. Dùng GET để tải tệp đã lưu; savedFormats trong trạng thái tác vụ liệt kê các định dạng hiện có. Việc lưu và tải xuống áp dụng cùng quy trình kiểm tra quyền sở hữu tác vụ, không tốn thêm tín dụng và không gia hạn thời hạn 24 giờ.
PUT /api/v1/translations/{id}/files/docx
X-Download-Kind: reading-copy
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: {bytes}
{binary DOCX body}
GET /api/v1/translations/{id}
{"savedFormats":["docx"],"savedDownloads":[{"format":"docx","kind":"reading-copy"}]}DELETE sẽ hủy công việc chưa hoàn tất hoặc xóa văn bản khả dụng và các tệp đã lưu. Xóa kết quả đã hoàn tất không hoàn lại tín dụng hoặc kéo dài thời gian tải xuống. Bản phát hành này không có webhook thông báo hoàn tất.
PUT /api/v1/translations/{id}/manifest
Content-Type: application/json
Content-Length: {bytes, maximum 2 MiB}
{"version":2,"parserVersion":"document-ir/9","fingerprint":"{original SHA-256}","ocr":[],"scans":[]}
PUT /api/v1/translations/{id}/source
Content-Type: application/octet-stream
Content-Length: {bytes, maximum 25 MiB}
X-Parser-Version: document-ir/9
X-Source-SHA256: {original SHA-256}
{unchanged original bytes}
GET /api/v1/translations/{id}
// sourceBackup is available only after both saves
GET /api/v1/translations/{id}/manifest
GET /api/v1/translations/{id}/sourceSố dư và lịch sử tài khoản
GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balanceLịch sử chỉ giới hạn cho chủ sở hữu hiện tại và sử dụng con trỏ phân trang được trả về. Điểm cuối số dư sử dụng phiên tài khoản trên trình duyệt và trả về thông tin đăng nhập cùng số dư ở mức tối thiểu. Khi Checkout đang chờ xử lý, hãy kiểm tra mỗi năm giây, tối đa mười lần; tạm dừng khi trang bị ẩn và dừng khi nhận được tín dụng hoặc tài khoản đăng xuất.
n8n, Make và Zapier
Dùng bước yêu cầu HTTP với thông tin xác thực Bearer bí mật. Trích xuất văn bản trước, POST tải trọng JSON đến điểm cuối báo giá, sau đó POST ID báo giá, tải trọng và khóa chống trùng lặp ổn định dài 16–80 ký tự đến điểm cuối bản dịch. Thêm độ trễ rồi GET trạng thái cho đến khi sẵn sàng, lấy kết quả và dựng lại hoặc lưu văn bản đã dịch. Lưu ID báo giá và khóa thử lại cùng bản ghi quy trình làm việc. Không cần trình kết nối chuyên dụng hoặc tải lên nhiều phần.
Giới hạn và lỗi
- Mỗi tài liệu tối đa 50.000 từ nguồn, 400.000 ký tự được trích xuất và 12.000 đoạn văn bản. Trình duyệt cũng giới hạn tệp gốc ở 25 MB, PDF ở 500 trang và tệp PowerPoint ở 500 trang chiếu. Đây là các giới hạn của nguồn, được kiểm tra trước khi bắt đầu dịch.
- Mỗi tài khoản có thể có tối đa 100 tài liệu đang chờ hoặc đang xử lý. Các khóa API dùng chung giới hạn 120 báo giá mỗi phút và năm lượt bắt đầu hoặc thử lại mới trong mỗi 10 giây cho mỗi tài khoản. Tuân thủ Retry-After trong phản hồi 429 và dùng thời gian chờ tăng dần có giới hạn khi gặp lỗi tạm thời; tăng tần suất thăm dò không giúp xử lý nhanh hơn.
- Chế độ đầu ra nghiêm ngặt sẽ từ chối các phần dịch bị thiếu, trùng lặp hoặc sai định dạng trước khi tính phí. Chế độ đầu ra tối đa sẽ giữ lại các bản dịch đã được xác thực và có thể giữ nguyên văn bản gốc trong các phần chưa xử lý; kết quả và sự cố sẽ mô tả kết quả. Nội dung tài liệu không bị thêm hình mờ hoặc ghi công dịch vụ.
Lỗi bao gồm thông báo lỗi và mã lỗi. 400 cho biết dữ liệu đầu vào không hợp lệ, 401 cho biết thông tin xác thực không hợp lệ, 402 cho biết không đủ tín dụng, 404 cho biết tác vụ không khả dụng, 409 cho biết báo giá hoặc trạng thái bị xung đột, 410 cho biết đã hết hạn, 429 cho biết giới hạn tốc độ hoặc dung lượng, còn 503 cho biết dịch vụ không khả dụng.
Chúng tôi giữ một bản sao riêng tư của tài liệu gốc trong 24 giờ sau khi dịch xong để bạn có thể khôi phục tệp tải xuống. Bạn có thể xóa bản sao sớm hơn bằng cách xóa bản dịch. Chúng tôi chỉ gửi văn bản đã trích xuất cho nhà cung cấp dịch vụ dịch thuật. Chi tiết quyền riêng tư