MultiTEL
Nhà phát triển

Tác vụ giọng nói và dịch thuật

Xác thực yêu cầu, thăm dò trạng thái tác vụ, gửi lại khi chưa rõ kết quả, thanh toán tác vụ đang chờ trả phí, kiểm tra mức sử dụng và xử lý lỗi cùng giới hạn.

Trên trang này
  1. Xác thực
  2. Thăm dò đến khi hoàn tất
  3. Thử lại an toàn các yêu cầu chưa rõ kết quả
  4. Mở kết quả sau khi nạp tiền
  5. Kiểm tra mức sử dụng
  6. Giới hạn
  7. Xử lý lỗi yêu cầu

Trong các ví dụ bên dưới, thay SERVICE bằng speech_to_text hoặc translate và thay JOB_ID bằng UUID được trả về. Mọi thao tác đều cần thông tin xác thực của tài khoản bạn, như mô tả trong phần Xác thực, và chỉ áp dụng trong phạm vi tài khoản sở hữu tác vụ. Có thể đọc tác vụ từ một trong hai máy chủ API, nhưng mỗi máy chủ dùng cấu trúc bao ngoài phản hồi riêng, vì vậy hãy sử dụng nhất quán một máy chủ.

Máy chủThành côngLỗi
api.multi.tel{"status":"success","data":{...}}{"status":"error","code":"...","message":"...","requestId":"..."}
api.multitel.net{"status":{"code":200},"response":{...}}{"status":{"code":409},"response":{"code":"idempotency_conflict"}}

Trên api.multitel.net, lỗi xác thực (401) được trả về trước khi áp dụng cấu trúc bao ngoài này và có thể có phần 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 phản hồi.

Xác thực

Mỗi yêu cầu phải mang thông tin xác thực của tài khoản bạn. Tác vụ, khóa idempotency, giới hạn, mức sử dụng và phí thuộc về tài khoản sở hữu thông tin xác thực. Chúng được dùng chung cho mọi bộ thông tin xác thực của tài khoản đó trên cả hai máy chủ, bất kể bộ thông tin nào gửi yêu cầu.

  • HTTP Basic (Authorization: Basic hoặc curl --user). Chấp nhận thông tin xác thực của tài khoản API loại mật khẩu, tài khoản phụ hoặc thông tin đăng nhập tài khoản của bạn. Chúng tôi khuyến nghị dùng tài khoản API riêng. Tên người dùng không được chứa dấu hai chấm; tên người dùng và mật khẩu đều không được để trống.
  • Token Bearer (Authorization: Bearer YOUR_TOKEN). Chấp nhận cho tài khoản API loại token. Tài khoản API dùng token phải có giới hạn IP và yêu cầu phải đến từ địa chỉ được phép. Cả hai máy chủ API chấp nhận địa chỉ IPv4 và dải CIDR đã cấu hình cho tài khoản. Không thể gửi token dưới dạng mật khẩu Basic. Hãy xác nhận token hoạt động trên máy chủ bạn sử dụng.
API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Nếu tài khoản API bị giới hạn theo địa chỉ IP, hãy gửi yêu cầu từ địa chỉ được phép. Thông tin xác thực thiếu hoặc không hợp lệ trả về 401. Trên api.multitel.net, thông tin xác thực hợp lệ nhưng không thể sử dụng các dịch vụ này, chẳng hạn thông tin tài khoản token gửi dưới dạng Basic, trả về 403 với mã unsupported_transcription_principal hoặc unsupported_translation_principal. Các lần xác thực thất bại lặp lại từ một địa chỉ trên api.multitel.net có thể khiến địa chỉ đó bị chặn, vì vậy hãy sửa thông tin xác thực trước khi thử lại.

Thăm dò đến khi hoàn tất

Gửi yêu cầu GET /v3/SERVICE/JOB_ID. Chúng tôi khuyến nghị thăm dò không thường xuyên hơn một lần mỗi 3 giây. Cấu trúc bao ngoài mô tả yêu cầu; kiểm tra trường status của tác vụ bên trong để xác định quá trình xử lý đã hoàn tất chưa.

Trạng tháiÝ nghĩa
queuedĐã chấp nhận và đang chờ. Các tác vụ của một tài khoản được xử lý lần lượt từng tác vụ, luân phiên với các tài khoản khác.
runningĐang xử lý. progress có thể là null; chỉ riêng giá trị null không có nghĩa tác vụ bị treo.
completedKết quả đã có. Lưu lại và đối chiếu các chi tiết quan trọng với nguồn.
failedKiểm tra failureCode. Công việc thất bại không bị tính phí. Sửa nguyên nhân rồi gửi với khóa mới; gửi lại cùng khóa sẽ trả về cùng tác vụ thất bại.
awaiting_paymentQuá trình xử lý đã xong nhưng số dư trả trước không đủ chi trả. Kết quả được lưu và giữ lại cho đến khi thanh toán tác vụ được hoàn tất.
API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

Trên api.multitel.net, đặt HOST thành https://api.multitel.net và đọc .response.id thay cho .data.id.

Thử lại an toàn các yêu cầu chưa rõ kết quả

Nếu quá thời gian chờ khi gửi tác vụ hoặc nhận mã 429 hay trạng thái 5xx, hãy gửi lại cùng dữ liệu đầu vào với cùng khóa idempotency. Phản hồi từ một trong hai máy chủ có thể bị mất hoặc thay bằng lỗi sau khi tác vụ đã được chấp nhận; gửi lại cùng khóa sẽ trả về tác vụ nếu đã tồn tại. Dùng lại khóa với dữ liệu đầu vào khác trả về 409 với mã idempotency_conflict. Một số lỗi lặp lại ở mọi lần thử, như 503 khi dịch vụ trả phí bị tắt hoặc 500 cho tệp âm thanh không đọc được, vì vậy hãy dừng sau vài lần thử.

Việc đổi khóa có tác động khác nhau tùy dịch vụ.

  • Với chuyển giọng nói thành văn bản, khóa mới tạo tác vụ mới và tính phí riêng nếu xử lý thành công. Khóa gốc tiếp tục trả về tác vụ gốc ngay cả sau khi quy trình xử lý được cập nhật.
  • Với dịch thuật, khóa mới có nội dung giống hệt trả về tác vụ tương ứng đang trong hàng đợi, đang xử lý, đã hoàn tất hoặc chờ thanh toán mà không tính phí mới. Công việc mới được tạo nếu tác vụ trước thất bại hoặc phiên bản xử lý đã thay đổi. Thử dịch lại bằng khóa gốc sau khi đổi phiên bản xử lý trả về 409, vì vậy hãy giữ ID tác vụ gốc và đọc tác vụ trực tiếp.

Mở kết quả sau khi nạp tiền

Với tác vụ ở trạng thái awaiting_payment, nạp tiền để số dư ít nhất bằng giá trị costUsd của tác vụ được làm tròn lên bội số tiếp theo của $0.00001, rồi gửi POST /v3/SERVICE/JOB_ID/settle. Các khoản khấu trừ được thực hiện theo bội số nguyên của $0.00001 và bao gồm phần dư chuyển từ các tác vụ trước của cùng dịch vụ, nên số tiền bị trừ có thể vượt costUsd với chênh lệch nhỏ hơn $0.00001. Trên api.multi.tel, gửi JSON {} hoặc phần nội dung rỗng; mọi thuộc tính trong phần nội dung đều bị từ chối với mã 400. api.multitel.net bỏ qua phần nội dung. Hoàn tất thanh toán sẽ mở kết quả đã lưu mà không chạy lại việc chuyển giọng nói thành văn bản hay dịch thuật. Phản hồi chứa tác vụ; kiểm tra trạng thái là completed. Nếu số dư vẫn không đủ, tác vụ vẫn ở trạng thái awaiting_payment và phản hồi vẫn là HTTP 200.

Với chuyển giọng nói thành văn bản, hoàn tất thanh toán tác vụ đã hoàn thành sẽ trả về tác vụ với duplicate: true, còn thanh toán tác vụ trong hàng đợi, đang xử lý hoặc đã thất bại trả về 409 với mã transcription_not_awaiting_payment. Với dịch thuật, thanh toán tác vụ ở bất kỳ trạng thái nào khác sẽ trả về tác vụ không thay đổi. Chỉ có thể hoàn tất thanh toán khi xử lý trả phí được bật (nếu không sẽ trả về 503). Tác vụ chờ thanh toán được tính là chi phí đã giữ chỗ, nên với tài khoản trả trước, chúng có thể chặn việc gửi tác vụ trả phí mới bằng mã 402 cho đến khi được thanh toán.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Kiểm tra mức sử dụng

Dùng GET /v3/SERVICE/usage. Các tham số tùy chọn from và to là ngày theo UTC ở định dạng YYYY-MM-DD, bao gồm cả hai ngày đầu và cuối. Nếu bỏ qua, from mặc định là ngày cách đây 30 ngày và to mặc định là hôm nay (UTC). to không được sớm hơn from, và hai ngày cách nhau tối đa 366 ngày (tối đa 367 ngày được tính). Ngày lịch không hợp lệ, khoảng đảo ngược hoặc dài hơn trả về 400; các tham số truy vấn khác trên api.multi.tel cũng vậy.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

Phản hồi chứa mode, currency (USD), from, to và days, là danh sách từ mới nhất đến cũ nhất.

  • Các mục chuyển giọng nói thành văn bản được nhóm theo ngày và nguồn. Chúng chứa date, source (api hoặc hpbx cho bản ghi Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd và debitedUsd.
  • Các mục dịch thuật được nhóm theo ngày, nguồn và bộ máy dịch. Chúng chứa date, source, engine, jobs, sourceCharacters, accruedUsd và debitedUsd.

accruedUsd là chi phí chính xác với chín chữ số thập phân, còn debitedUsd là số tiền đã khấu trừ với năm chữ số thập phân. Mức sử dụng được ghi vào ngày UTC mà phí của từng tác vụ được thanh toán, nên tác vụ trong hàng đợi, đang xử lý, thất bại và chờ thanh toán không xuất hiện.

Giới hạn

Mỗi tài khoản có tối đa tổng cộng 50 tác vụ chuyển giọng nói thành văn bản và dịch thuật chưa hoàn tất: trong hàng đợi, đang xử lý hoặc chờ thanh toán, bao gồm xử lý bản ghi Hosted PBX. Khi đạt giới hạn đó hoặc tổng năng lực dịch vụ, yêu cầu gửi tác vụ trả về 429 với mã transcription_queue_full hoặc translation_queue_full. api.multi.tel cũng giới hạn mỗi địa chỉ IP của máy khách ở mức 300 yêu cầu mỗi phút cho tất cả yêu cầu đến máy chủ đó. Giới hạn này trả về 429 với các tiêu đề giới hạn tốc độ và phần nội dung văn bản thuần thay vì cấu trúc bao ngoài lỗi JSON.

Xử lý lỗi yêu cầu

Trên máy chủ chính, lỗi trả về trạng thái lỗi HTTP và JSON chứa status: "error", code, message và requestId. Mỗi phản hồi cũng có tiêu đề X-Request-ID. Bạn có thể cung cấp giá trị riêng; giá trị dài hơn 128 ký tự sẽ bị cắt ngắn. Máy chủ tương thích chỉ trả về mã lỗi trong response.code. Ghi lại ID yêu cầu, nếu có, và mã lỗi; không đưa âm thanh, văn bản hay thông tin xác thực vào nhật ký.

Các trạng thái thường gặp:

Trạng tháiÝ nghĩa
400Dữ liệu đầu vào không hợp lệ.
401Thông tin xác thực thiếu hoặc không hợp lệ.
402Số dư trả trước không đủ.
403Trên máy chủ tương thích, thông tin xác thực không thể sử dụng các dịch vụ này.
404Tác vụ hoặc tuyến không xác định.
405Phương thức không được hỗ trợ hoặc đường dẫn không xác định trong dịch vụ.
409Dữ liệu đầu vào xung đột, dịch sang cùng ngôn ngữ hoặc thanh toán tác vụ giọng nói không chờ thanh toán.
413Phần nội dung hoặc tệp quá lớn.
422Âm thanh không được hỗ trợ hoặc cặp ngôn ngữ tiêu chuẩn không khả dụng.
429Giới hạn hàng đợi, kiểm tra tính hợp lệ hoặc tốc độ yêu cầu.
500Lỗi máy chủ không mong đợi, bao gồm tệp âm thanh không đọc được.
503Dịch vụ bị tắt hoặc tạm thời không khả dụng, hoặc thông tin xác thực hiện không thể kiểm tra.

Làm theo mã lỗi được trả về thay vì cho rằng mọi lỗi kiểm tra tính hợp lệ đều có cùng trạng thái.

Với 429 hoặc 503, chờ rồi thử lại với thời gian chờ tăng dần và cùng khóa gửi tác vụ; tuân theo Retry-After nếu có tiêu đề này. Với dữ liệu đầu vào hoặc thông tin xác thực không hợp lệ, sửa nguyên nhân trước. Không liên tục gửi khóa mới khi các tác vụ trước vẫn đang trong hàng đợi.