Tài liệu API Chuyển đổi thành văn bản phương tiện

Giá cả

25 credits cho mỗi yêu cầu

Chi phí cố định bất kể độ dài phương tiện hay kích thước tệp.

Tổng quan

Endpoint Chuyển đổi thành văn bản phương tiện là một phần của bộ API Revid, cung cấp khả năng chuyển đổi âm thanh/video thành văn bản và dịch thuật.

Tutorials RevidAPI

Endpoint

URL: https://api.revidapi.com/paid/media/transcribe
Method: POST

Yêu cầu

Headers

x-api-key: Bắt buộc. Khóa xác thực cho quyền truy cập API.
Content-Type: Bắt buộc. Phải là application/json.

Tham số Body

Tham số bắt buộc

media_url (string)
Định dạng: URI
Mô tả: URL của tệp phương tiện cần chuyển đổi thành văn bản

Tham số tùy chọn

task (string)
Giá trị cho phép: "transcribe", "translate"
Mặc định: "transcribe"
Mô tả: Chỉ định có chuyển đổi thành văn bản hay dịch âm thanh
include_text (boolean)
Mặc định: true
Mô tả: Bao gồm văn bản chuyển đổi dạng thuần trong phản hồi
include_srt (boolean)
Mặc định: false
Mô tả: Bao gồm phụ đề định dạng SRT trong phản hồi
include_segments (boolean)
Mặc định: false
Mô tả: Bao gồm các đoạn có timestamp trong phản hồi
word_timestamps (boolean)
Mặc định: false
Mô tả: Bao gồm timestamp cho từng từ riêng lẻ
response_type (string)
Giá trị cho phép: "direct", "cloud"
Mặc định: "direct"
Mô tả: Có trả về kết quả trực tiếp hay dưới dạng URL cloud storage
language (string)
Tùy chọn
Mô tả: Mã ngôn ngữ nguồn cho việc chuyển đổi thành văn bản
webhook_url (string)
Định dạng: URI
Mô tả: URL để nhận kết quả chuyển đổi thành văn bản không đồng bộ
id (string)
Mô tả: Mã định danh tùy chỉnh cho công việc chuyển đổi thành văn bản
max_words_per_line (integer)
Tối thiểu: 1
Mô tả: Điều khiển số lượng từ tối đa mỗi dòng trong tệp SRT. Khi được chỉ định, văn bản của mỗi đoạn sẽ được chia thành nhiều dòng với tối đa số lượng từ được chỉ định mỗi dòng.

Ví dụ yêu cầu

curl -X POST "https://api.revidapi.com/paid/media/transcribe" \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "media_url": "https://example.com/media/file.mp3",
    "task": "transcribe",
    "include_text": true,
    "include_srt": true,
    "include_segments": true,
    "response_type": "cloud",
    "webhook_url": "https://your-webhook.com/callback",
    "id": "custom-job-123",
    "max_words_per_line": 5
  }'

Phản hồi

Phản hồi ngay lập tức (202 Accepted)

Khi cung cấp webhook URL, API trả về xác nhận ngay lập tức:

{
  "code": 202,
  "id": "custom-job-123",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "processing",
  "pid": 12345,
  "queue_id": 67890,
  "max_queue_length": "unlimited",
  "queue_length": 1,
  "build_number": "1.0.0"
}

Phản hồi thành công (qua Webhook)

Đối với response_type trực tiếp:

{
  "endpoint": "/v1/transcribe/media",
  "code": 200,
  "id": "custom-job-123",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "response": {
    "text": "Nội dung văn bản đã chuyển đổi...",
    "srt": "Nội dung định dạng SRT...",
    "segments": [...],
    "text_url": null,
    "srt_url": null,
    "segments_url": null
  },
  "message": "success",
  "pid": 12345,
  "queue_id": 67890,
  "run_time": 5.234,
  "queue_time": 0.123,
  "total_time": 5.357,
  "queue_length": 0,
  "build_number": "1.0.0"
}

Đối với response_type cloud:

{
  "endpoint": "/v1/transcribe/media",
  "code": 200,
  "id": "custom-job-123",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "response": {
    "text": null,
    "srt": null,
    "segments": null,
    "text_url": "https://storage.example.com/text.txt",
    "srt_url": "https://storage.example.com/subtitles.srt",
    "segments_url": "https://storage.example.com/segments.json"
  },
  "message": "success",
  "pid": 12345,
  "queue_id": 67890,
  "run_time": 5.234,
  "queue_time": 0.123,
  "total_time": 5.357,
  "queue_length": 0,
  "build_number": "1.0.0"
}

Phản hồi lỗi

Hàng đợi đầy (429 Too Many Requests)

{
  "code": 429,
  "id": "custom-job-123",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "MAX_QUEUE_LENGTH (100) reached",
  "pid": 12345,
  "queue_id": 67890,
  "queue_length": 100,
  "build_number": "1.0.0"
}

Lỗi server (500 Internal Server Error)

{
  "endpoint": "/v1/transcribe/media",
  "code": 500,
  "id": "custom-job-123",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "response": null,
  "message": "Chi tiết thông báo lỗi",
  "pid": 12345,
  "queue_id": 67890,
  "run_time": 0.123,
  "queue_time": 0.056,
  "total_time": 0.179,
  "queue_length": 1,
  "build_number": "1.0.0"
}

Xử lý lỗi

Lỗi phổ biến

API Key không hợp lệ: 401 Unauthorized
Payload JSON không hợp lệ: 400 Bad Request
Thiếu trường bắt buộc: 400 Bad Request
media_url không hợp lệ: 400 Bad Request
Hàng đợi đầy: 429 Too Many Requests
Lỗi xử lý: 500 Internal Server Error

Lỗi xác thực

Endpoint thực hiện xác thực nghiêm ngặt của payload yêu cầu bằng JSON Schema. Các lỗi xác thực phổ biến bao gồm: - Định dạng URI không hợp lệ cho media_url hoặc webhook_url - Giá trị task không hợp lệ (phải là "transcribe" hoặc "translate") - Giá trị response_type không hợp lệ (phải là "direct" hoặc "cloud") - Thuộc tính không xác định trong body yêu cầu

Ghi chú sử dụng

Xử lý Webhook
Khi cung cấp webhook_url, yêu cầu được xử lý không đồng bộ
API trả về phản hồi 202 ngay lập tức với job_id
Kết quả cuối cùng được gửi đến webhook_url khi xử lý hoàn tất
Quản lý hàng đợi
Các yêu cầu với webhook_url được đưa vào hàng đợi để xử lý
Biến môi trường MAX_QUEUE_LENGTH điều khiển kích thước hàng đợi
Đặt MAX_QUEUE_LENGTH thành 0 để kích thước hàng đợi không giới hạn
Quản lý tệp
Đối với response_type cloud, các tệp tạm thời được tự động dọn dẹp
Kết quả được tải lên cloud storage trước khi xóa
URL trong phản hồi cung cấp quyền truy cập vào các tệp đã lưu trữ
Định dạng SRT
Tham số max_words_per_line cho phép kiểm soát số lượng từ tối đa mỗi dòng trong tệp SRT
Khi được chỉ định, văn bản của mỗi đoạn sẽ được chia thành nhiều dòng với tối đa số lượng từ được chỉ định mỗi dòng
Điều này hữu ích để tạo phụ đề dễ đọc hơn với độ dài dòng nhất quán

Vấn đề thường gặp

Truy cập phương tiện
Đảm bảo media_url có thể truy cập công khai
Xác minh định dạng tệp phương tiện được hỗ trợ
Kiểm tra tệp phương tiện có bị hỏng không
Gửi Webhook
Đảm bảo webhook_url có thể truy cập công khai
Triển khai logic thử lại endpoint webhook
Giám sát khả năng sử dụng endpoint webhook
Sử dụng tài nguyên
Tệp phương tiện lớn có thể mất thời gian xử lý đáng kể
Giám sát độ dài hàng đợi cho các triển khai production
Cân nhắc triển khai giới hạn kích thước yêu cầu

Thực hành tốt nhất

Xử lý yêu cầu
Luôn cung cấp id duy nhất để theo dõi công việc
Triển khai logic thử lại webhook
Lưu trữ job_id để tương quan kết quả
Quản lý tài nguyên
Giám sát độ dài hàng đợi trong production
Triển khai xử lý timeout phù hợp
Sử dụng response_type cloud cho tệp lớn
Xử lý lỗi
Triển khai xử lý lỗi webhook toàn diện
Ghi nhật ký job_id với tất cả các hoạt động liên quan
Giám sát thời gian xử lý và tỷ lệ lỗi
Bảo mật
Sử dụng HTTPS cho media_url và webhook_url
Triển khai xác thực webhook
Xác thực loại tệp phương tiện trước khi xử lý

Giá cả

25 credits cho mỗi yêu cầu

Chi phí cố định bất kể độ dài phương tiện hay kích thước tệp.

Kiểm tra Trạng thái Công việc

Sau khi gửi một công việc, bạn có thể kiểm tra trạng thái của nó bằng cách sử dụng job_id được trả về trong phản hồi.

Endpoint

URL Path: https://api.revidapi.com/paid/get/job/status
HTTP Method: POST

Yêu cầu

Headers

x-api-key (bắt buộc): API key để xác thực.
Content-Type: application/json

Tham số Body

{
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}

Ví dụ Yêu cầu

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"}' \
  https://api.revidapi.com/paid/get/job/status

Phản hồi

Phản hồi Thành công

{
  "endpoint": "/v1/toolkit/job/status",
  "code": 200,
  "id": null,
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  "response": {
    "job_status": "done",
    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "queue_id": 140368864456064,
    "process_id": 123456,
    "response": {
      "endpoint": "/v1/endpoint/name",
      "code": 200,
      "id": "request-123",
      "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
      "response": "https://cloud-storage.example.com/output.mp4",
      "message": "success",
      "pid": 123456,
      "queue_id": 140368864456064,
      "run_time": 2.345,
      "queue_time": 0.123,
      "total_time": 2.468,
      "queue_length": 0,
      "build_number": "1.0.0"
    }
  },
  "message": "success",
  "pid": 123456,
  "queue_id": 140368864456064,
  "run_time": 0.001,
  "queue_time": 0.0,
  "total_time": 0.001,
  "queue_length": 0,
  "build_number": "1.0.0"
}

Phản hồi Lỗi

404 Not Found: Nếu không tìm thấy công việc với job_id được cung cấp:

{
  "error": "Job not found",
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}

500 Internal Server Error: Nếu xảy ra lỗi không mong muốn:

{
  "error": "Failed to retrieve job status: <error_message>",
  "code": 500
}