Bỏ qua để đến nội dung

Tích hợp quy trình làm việc tài liệu vào ứng dụng của bạn

Từ việc tải lên một tệp, dịch tệp đó, kiểm tra tiến trình cho đến tải xuống kết quả. Mỗi bước đều được giải thích theo thứ tự tích hợp, với các điểm truy cập dành cho quản lý tệp, xử lý tài liệu và các dịch vụ âm thanh, video.

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.

01 Bắt đầu bằng một yêu cầu không tốn tín dụng

Phần tiêu đề “01 Bắt đầu bằng một yêu cầu không tốn tín dụng”

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.

  1. 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.

  2. 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ý.

    Terminal window
    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"

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ướcPhương pháp và đường dẫnNhững gì cần giữ nguyên
Yêu cầu tải lênPOST /upload/presignupload_url, upload_headers, finalize_token
Gửi tệpPUT đế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ênPOST /upload/finalizedocument.id
Tạo một bản dịchPOST /jobsCông việc id
Kiểm tra trạng tháiGET /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}/downloadSố 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.

03 Tìm điểm kết thúc cho tác vụ của bạn

Phần tiêu đề “03 Tìm điểm kết thúc cho tác vụ của bạn”

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.

04 Xác thực và quyền sở hữu tài nguyên

Phần tiêu đề “04 Xác thực và quyền sở hữu tài nguyên”

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.

05 Tích hợp xử lý lỗi build vào quy trình tích hợp

Phần tiêu đề “05 Tích hợp xử lý lỗi build vào quy trình tích hợp”

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.

  • Tạo idempotent : tạo một 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.
  • Thông báo bất đồng bộ : việc polling là ổn cho lần tích hợp đầu tiên; để theo dõi tiến trình liên tục, hãy sử dụng SSE , và để nhận các trạng thái cuối cùng ở chế độ nền, hãy sử dụng một webhook . .
Trạng tháiKiểm tra trước tiênLàm gì
401 / 403Khóa, quyền hạn, quyền sở hữu tài nguyênHã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.
402Tín dụng khả dụngNạp tiền, sau đó gửi lại
409Khóa và nội dung của tính idempotent, trạng thái tài nguyênTruy vấn thao tác gốc trước khi bắt đầu thao tác mới
422Lỗi trường trong phản hồiHãy sửa các tham số hoặc tệp
429Kinh doanh code và Retry-AfterGiớ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.
5xxLỗi dịch vụ tạm thờiRú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.

06 Kiểm tra cách tính phí trước khi tích hợp

Phần tiêu đề “06 Kiểm tra cách tính phí trước khi tích hợp”

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 đó.