Tiêu đề yêu cầu
Sử dụng X-API-Key: sk_… hoặc Authorization: Bearer sk_…, chỉ được dùng một trong hai cho mỗi yêu cầu. Gửi Content-Type: application/json kèm theo các phần thân JSON.
Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · Xác thực bằng khóa API · các lần dịch tệp được xử lý dưới dạng tác vụ không đồng bộ
Trang web này mô tả API đám mây HTTP.
Hãy xác nhận rằng khóa và mạng của bạn hoạt động bình thường trước khi tải tệp lên. Thao tác kiểm tra số dư không mất tín dụng và không tạo ra công việc dịch thuật nào.
Lấy một khóa API
Đăng nhập vào API console và tạo một khóa bắt đầu bằng sk_. Sử dụng một khóa riêng cho mỗi ứng dụng và đặt ngân sách cho khóa đó.
Một khóa được dùng cho tài khoản đã tạo ra nó. Hãy giữ khóa này trên máy chủ và đọc từ biến môi trường; không bao giờ lưu khóa vào mã nguồn trang web hoặc kho công khai.
Kiểm tra số dư
Thiết lập biến môi trường OMNIDOC_API_KEY, sau đó chạy bất kỳ ví dụ nào dưới đây. Kết quả thành công trả về JSON; 401 có nghĩa là khóa gặp sự cố và cần được kiểm tra. Không bao giờ hiển thị toàn bộ khóa trong phiếu hỗ trợ, ảnh chụp màn hình hoặc nhật ký.
export OMNIDOC_API_KEY="sk_your_key"curl --fail-with-body --silent --show-error \ 'https://omnidoc.top/api/v1/billing/credits/balance' \ -H "X-API-Key: $OMNIDOC_API_KEY"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+, save as balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('Set OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());Việc tải lên thành công chỉ có nghĩa là tệp đã được lưu trữ. Sau khi bạn tạo một tác vụ, hãy đợi tác vụ đạt trạng thái cuối cùng, rồi liệt kê và tải xuống kết quả của nó.
| Bước | Phương pháp và đường dẫn | Những gì cần giữ nguyên |
|---|---|---|
| Yêu cầu tải lên | POST /upload/presign | upload_url, upload_headers, finalize_token |
| Gửi tệp | PUT đến upload_url được trả về | Phản hồi thành công; yêu cầu này không chứa khóa API |
| Xác nhận việc tải lên | POST /upload/finalize | document.id |
| Tạo một bản dịch | POST /jobs | Công việc id |
| Kiểm tra trạng thái | GET /jobs/{job_id} | completed hoặc failed |
| Liệt kê kết quả | GET /artifacts?job_id={job_id} | ID và định dạng của Artifact |
| Tải xuống kết quả | GET /artifacts/{artifact_id}/download | Số byte của tệp và tên tệp phản hồi |
Đối với việc tải lên trực tiếp, hãy gửi upload_headers từ máy chủ chính xác như giá trị được trả về và không bao giờ gửi X-API-Key đến địa chỉ lưu trữ. Nếu địa chỉ tải lên hết hạn hoặc quá trình chuyển giao thất bại, hãy yêu cầu một địa chỉ mới. Chi tiết: giao thức tải lên, bắt đầu nhanh, quy trình Node.js đầy đủ và trường yêu cầu dịch thuật.
Mỗi mục đều liệt kê các đường dẫn, trường yêu cầu và ví dụ. Trạng thái dịch vụ của tài khoản bạn cùng với giới hạn của khóa của bạn đều áp dụng cho tất cả chúng.
Một khóa API dùng để định danh tài khoản. Đây không phải là mật khẩu tải xuống công khai cho tệp.
Tiêu đề yêu cầu
Sử dụng X-API-Key: sk_… hoặc Authorization: Bearer sk_…, chỉ được dùng một trong hai cho mỗi yêu cầu. Gửi Content-Type: application/json kèm theo các phần thân JSON.
Điều mà một khóa có thể đạt tới
Một khóa chỉ có quyền truy cập vào các tài nguyên mà tài khoản của nó được phép sử dụng; trạng thái dịch vụ, ngân sách của khóa và các cài đặt dịch thuật được phép vẫn được áp dụng. Các thay đổi đối với tài khoản cũng như việc tạo, xoay vòng hoặc thu hồi khóa đều được thực hiện trong bảng điều khiển.
Xem xác thực, ngân sách và xoay vòng và dịch vụ và quyền hạn.
Thời gian chờ hết không có nghĩa là tác vụ chưa được tạo. Phân biệt các lỗi có thể thử lại với những yêu cầu cần sửa, để không có bất kỳ thao tác nào bị gửi hoặc xử lý hai lần.
Idempotency-Key cho mỗi thao tác tạo mới; khi bạn thử lại cùng một thao tác, hãy tái sử dụng khóa gốc và chính xác cùng một thân yêu cầu. Các thao tác tài liệu, công việc phương tiện và tạo giọng nói yêu cầu khóa này; đối với các điểm cuối tạo khác, vui lòng xem các trang tham chiếu tương ứng.| Trạng thái | Kiểm tra trước tiên | Làm gì |
|---|---|---|
401 / 403 | Khóa, quyền hạn, quyền sở hữu tài nguyên | Hãy sửa thông tin xác thực hoặc quyền; không được thử lại một cách mù quáng. |
402 | Tín dụng khả dụng | Nạp tiền, sau đó gửi lại |
409 | Khóa và nội dung của tính idempotent, trạng thái tài nguyên | Truy vấn thao tác gốc trước khi bắt đầu thao tác mới |
422 | Lỗi trường trong phản hồi | Hãy sửa các tham số hoặc tệp |
429 | Kinh doanh code và Retry-After | Giới hạn về tỷ lệ và hàng đợi có thể được chờ hết; trước tiên phải nâng cấp ngân sách khóa đã sử dụng hết. |
5xx | Lỗi dịch vụ tạm thời | Rút lui theo cấp số nhân có giới hạn; giữ nguyên khóa tính không đổi cho các yêu cầu tạo |
Giữ nguyên tiêu đề phản hồi X-Request-Id, thời gian yêu cầu và đường dẫn để phục vụ việc khắc phục sự cố; không bao giờ ghi nhật ký toàn bộ khóa. Tất cả mã lỗi và ví dụ thử lại đều có trong tham chiếu lỗi.
Không có tín dụng
Việc tải lên, kiểm tra công việc, tải xuống kết quả và đọc số dư cũng như hồ sơ thanh toán không tốn tín dụng; các từ điển thuật ngữ, dự án, thẻ, tính năng tìm kiếm và chia sẻ cũng vậy.
Tính phí theo mức sử dụng
Dịch tệp, công cụ tài liệu, dịch tức thì và các dịch vụ âm thanh, video được tính phí dựa trên mức sử dụng thực tế; việc tạo tác vụ không phải là khoản tính phí cuối cùng.
Trước khi một tác vụ bắt đầu, chỉ có ngưỡng số dư được kiểm tra; sau khi hoàn tất, mức sử dụng thực tế sẽ được tính phí. Nếu số dư không đủ, phần chênh lệch sẽ được ghi nhận dưới dạng nợ, và các khoản tín dụng đến sau sẽ được dùng để thanh toán trước. Bạn có thể đối chiếu chi phí và hoàn tiền theo từng tác vụ hoặc theo từng giao dịch tín dụng. Khi ngân sách của một khóa đã hết, bạn vẫn có thể truy vấn các tác vụ, kết quả và bản ghi liên quan đến khóa đó.