Bỏ qua

Endpoint Thêm phụ đề video (v1)

Giá cả

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

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

1. Tổng quan

Endpoint https://api.revidapi.com/paid/video/caption là một phần của Video API và chịu trách nhiệm thêm phụ đề vào tệp video. Nó chấp nhận URL video, văn bản phụ đề, và các tùy chọn tạo kiểu khác nhau cho phụ đề.

2. Endpoint

URL: https://api.revidapi.com/paid/video/caption Method: POST

3. Yêu cầu

Headers

  • x-api-key: Bắt buộc. API key để xác thực.

Tham số Body

Body yêu cầu phải là đối tượng JSON với các thuộc tính sau:

  • video_url (string, bắt buộc): URL của tệp video cần thêm phụ đề.
  • captions (string, tùy chọn): Có thể là một trong các loại sau:
  • Văn bản phụ đề thô để thêm vào video
  • URL đến tệp phụ đề SRT
  • URL đến tệp phụ đề ASS
  • Nếu không được cung cấp, hệ thống sẽ tự động tạo phụ đề bằng cách chuyển đổi âm thanh từ video thành văn bản
  • settings (object, tùy chọn): Đối tượng chứa các tùy chọn tạo kiểu khác nhau cho phụ đề. Xem schema bên dưới để biết các tùy chọn có sẵn.
  • replace (mảng, tùy chọn): Mảng các đối tượng với các thuộc tính find và replace, chỉ định các thay thế văn bản cần thực hiện trong phụ đề.
  • webhook_url (string, tùy chọn): URL để nhận thông báo webhook khi quá trình thêm phụ đề hoàn tất.
  • id (string, tùy chọn): Mã định danh cho yêu cầu.
  • language (string, tùy chọn): Mã ngôn ngữ cho phụ đề (ví dụ: "en", "fr"). Mặc định là "auto".
  • exclude_time_ranges (mảng, tùy chọn): Danh sách các khoảng thời gian cần bỏ qua khi thêm phụ đề. Mỗi mục phải là đối tượng với:
  • start: (string, bắt buộc) Thời gian bắt đầu của khoảng bị loại trừ, dưới dạng chuỗi timecode theo định dạng hh:mm:ss.ms (ví dụ: 00:01:23.456).
  • end: (string, bắt buộc) Thời gian kết thúc, dưới dạng chuỗi timecode theo định dạng hh:mm:ss.ms, phải lớn hơn nghiêm ngặt start. Nếu bất kỳ giá trị nào không phải là chuỗi timecode hợp lệ, hoặc nếu end không lớn hơn start, yêu cầu sẽ trả về lỗi.

Schema Settings

{
    "type": "object",
    "properties": {
        "line_color": {"type": "string"},
        "word_color": {"type": "string"},
        "outline_color": {"type": "string"},
        "all_caps": {"type": "boolean"},
        "max_words_per_line": {"type": "integer"},
        "x": {"type": "integer"},
        "y": {"type": "integer"},
        "position": {
            "type": "string",
            "enum": [
                "bottom_left", "bottom_center", "bottom_right",
                "middle_left", "middle_center", "middle_right",
                "top_left", "top_center", "top_right"
            ]
        },
        "alignment": {
            "type": "string",
            "enum": ["left", "center", "right"]
        },
        "font_family": {"type": "string"},
        "font_size": {"type": "integer"},
        "bold": {"type": "boolean"},
        "italic": {"type": "boolean"},
        "underline": {"type": "boolean"},
        "strikeout": {"type": "boolean"},
        "style": {
            "type": "string",
            "enum": [
                "classic",     // Phụ đề thông thường với toàn bộ văn bản được hiển thị cùng lúc
                "karaoke",     // Làm nổi bật từng từ theo trình tự theo phong cách karaoke
                "highlight",   // Hiển thị toàn bộ văn bản nhưng làm nổi bật từ hiện tại
                "underline",   // Hiển thị toàn bộ văn bản nhưng gạch chân từ hiện tại
                "word_by_word" // Hiển thị một từ tại một thời điểm
            ]
        },
        "outline_width": {"type": "integer"},
        "spacing": {"type": "integer"},
        "angle": {"type": "integer"},
        "shadow_offset": {"type": "integer"}
    },
    "additionalProperties": false
}

Ví dụ yêu cầu

Ví dụ 1: Thêm phụ đề tự động cơ bản

{
    "video_url": "https://example.com/video.mp4"
}
Yêu cầu tối thiểu này sẽ tự động chuyển đổi video thành văn bản và thêm phụ đề màu trắng ở giữa dưới cùng.

Ví dụ 2: Văn bản tùy chỉnh với tạo kiểu

{
    "video_url": "https://example.com/video.mp4",
    "captions": "Đây là văn bản phụ đề mẫu.",
    "settings": {
        "style": "classic",
        "line_color": "#FFFFFF",
        "outline_color": "#000000",
        "position": "bottom_center",
        "alignment": "center",
        "font_family": "Arial",
        "font_size": 24,
        "bold": true
    }
}

Ví dụ 3: Phụ đề kiểu Karaoke với các tùy chọn nâng cao

{
    "video_url": "https://example.com/video.mp4",
    "settings": {
        "line_color": "#FFFFFF",
        "word_color": "#FFFF00",
        "outline_color": "#000000",
        "all_caps": false,
        "max_words_per_line": 10,
        "position": "bottom_center",
        "alignment": "center",
        "font_family": "Arial",
        "font_size": 24,
        "bold": false,
        "italic": false,
        "style": "karaoke",
        "outline_width": 2,
        "shadow_offset": 2
    },
    "replace": [
        {
            "find": "um",
            "replace": ""
        },
        {
            "find": "like",
            "replace": ""
        }
    ],
    "webhook_url": "https://example.com/webhook",
    "id": "request-123",
    "language": "en"
}

Ví dụ 4: Sử dụng tệp phụ đề bên ngoài

{
    "video_url": "https://example.com/video.mp4",
    "captions": "https://example.com/subtitles.srt",
    "settings": {
        "line_color": "#FFFFFF",
        "outline_color": "#000000",
        "position": "bottom_center",
        "font_family": "Arial",
        "font_size": 24
    }
}

Ví dụ 5: Loại trừ khoảng thời gian khỏi việc thêm phụ đề

{
    "video_url": "https://example.com/video.mp4",
    "settings": {
        "style": "classic",
        "line_color": "#FFFFFF",
        "outline_color": "#000000",
        "position": "bottom_center",
        "font_family": "Arial",
        "font_size": 24
    },
    "exclude_time_ranges": [
        { "start": "00:00:10.000", "end": "00:00:20.000" },
        { "start": "00:00:30.000", "end": "00:00:40.000" }
    ]
}

curl -X POST \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
        "video_url": "https://example.com/video.mp4",
        "settings": {
            "line_color": "#FFFFFF",
            "word_color": "#FFFF00",
            "outline_color": "#000000",
            "all_caps": false,
            "max_words_per_line": 10,
            "position": "bottom_center",
            "alignment": "center",
            "font_family": "Arial",
            "font_size": 24,
            "style": "karaoke",
            "outline_width": 2
        },
        "replace": [
            {
                "find": "um",
                "replace": ""
            }
        ],
        "id": "custom-request-id"
    }' \
    https://api.revidapi.com/paid/video/caption

4. Phản hồi

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

Phản hồi sẽ là đối tượng JSON với các thuộc tính sau:

  • code (integer): Mã trạng thái HTTP (200 cho thành công).
  • id (string): Mã định danh yêu cầu, nếu được cung cấp trong yêu cầu.
  • job_id (string): Mã định danh duy nhất cho công việc.
  • response (string): URL cloud của tệp video đã thêm phụ đề.
  • message (string): Thông báo thành công.
  • pid (integer): ID tiến trình của worker xử lý yêu cầu.
  • queue_id (integer): ID của hàng đợi được sử dụng để xử lý yêu cầu.
  • run_time (float): Thời gian thực hiện để xử lý yêu cầu (tính bằng giây).
  • queue_time (float): Thời gian yêu cầu ở trong hàng đợi (tính bằng giây).
  • total_time (float): Tổng thời gian thực hiện cho yêu cầu (tính bằng giây).
  • queue_length (integer): Độ dài hiện tại của hàng đợi xử lý.
  • build_number (string): Số build của ứng dụng.

Ví dụ:

{
    "code": 200,
    "id": "request-123",
    "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "response": "https://cloud.example.com/captioned-video.mp4",
    "message": "success",
    "pid": 12345,
    "queue_id": 140682639937472,
    "run_time": 5.234,
    "queue_time": 0.012,
    "total_time": 5.246,
    "queue_length": 0,
    "build_number": "1.0.0"
}

Phản hồi lỗi

Thiếu hoặc tham số không hợp lệ

Mã trạng thái: 400 Bad Request

{
    "code": 400,
    "id": "request-123",
    "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "message": "Missing or invalid parameters",
    "pid": 12345,
    "queue_id": 140682639937472,
    "queue_length": 0,
    "build_number": "1.0.0"
}

Lỗi font

Mã trạng thái: 400 Bad Request

{
    "code": 400,
    "error": "The requested font 'InvalidFont' is not available. Please choose from the available fonts.",
    "available_fonts": ["Arial", "Times New Roman", "Courier New", ...],
    "pid": 12345,
    "queue_id": 140682639937472,
    "queue_length": 0,
    "build_number": "1.0.0"
}

Lỗi máy chủ nội bộ

Mã trạng thái: 500 Internal Server Error

{
    "code": 500,
    "id": "request-123",
    "job_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "error": "An unexpected error occurred during the captioning process.",
    "pid": 12345,
    "queue_id": 140682639937472,
    "queue_length": 0,
    "build_number": "1.0.0"
}

5. Xử lý lỗi

Endpoint xử lý các lỗi phổ biến sau:

  • Thiếu hoặc tham số không hợp lệ: Nếu bất kỳ tham số bắt buộc nào bị thiếu hoặc không hợp lệ, lỗi 400 Bad Request được trả về với thông báo lỗi mô tả.
  • Lỗi font: Nếu font được yêu cầu không có sẵn, lỗi 400 Bad Request được trả về với danh sách các font có sẵn.
  • Lỗi máy chủ nội bộ: Nếu có lỗi không mong muốn xảy ra trong quá trình thêm phụ đề, lỗi 500 Internal Server Error được trả về với thông báo lỗi.

Ngoài ra, ngữ cảnh ứng dụng chính (app.py) bao gồm xử lý lỗi cho quá tải hàng đợi. Nếu độ dài hàng đợi tối đa (MAX_QUEUE_LENGTH) được đặt và kích thước hàng đợi đạt đến giới hạn đó, lỗi 429 Too Many Requests được trả về với thông báo mô tả.

6. Ghi chú sử dụng

  • Tham số video_url phải là URL hợp lệ trỏ đến tệp video (MP4, MOV, v.v.).
  • Tham số captions là tùy chọn và có thể được sử dụng theo nhiều cách:
  • Nếu không được cung cấp, endpoint sẽ tự động chuyển đổi âm thanh thành văn bản và tạo phụ đề
  • Nếu được cung cấp dưới dạng văn bản thuần, văn bản sẽ được sử dụng làm phụ đề cho toàn bộ video
  • Nếu được cung cấp dưới dạng URL đến tệp phụ đề SRT hoặc ASS, hệ thống sẽ sử dụng tệp đó để thêm phụ đề
  • Đối với tệp SRT, chỉ hỗ trợ kiểu 'classic'
  • Đối với tệp ASS, tạo kiểu gốc sẽ được giữ nguyên
  • Tham số settings cho phép tùy chỉnh giao diện và hành vi của phụ đề:
  • style xác định cách phụ đề được hiển thị, với các tùy chọn bao gồm:
    • classic: Phụ đề thông thường với toàn bộ văn bản được hiển thị cùng lúc
    • karaoke: Làm nổi bật từng từ theo trình tự theo phong cách karaoke khi chúng được nói
    • highlight: Hiển thị toàn bộ văn bản phụ đề nhưng làm nổi bật mỗi từ khi nó được nói
    • underline: Hiển thị toàn bộ văn bản phụ đề nhưng gạch chân mỗi từ khi nó được nói
    • word_by_word: Chỉ hiển thị một từ tại một thời điểm
  • position có thể được sử dụng để đặt phụ đề ở một trong chín vị trí trên màn hình
  • alignment xác định căn chỉnh văn bản trong vị trí (trái, giữa, phải)
  • font_family có thể là bất kỳ font hệ thống nào có sẵn
  • Các tùy chọn màu sắc có thể được đặt bằng mã hex (ví dụ: "#FFFFFF" cho màu trắng)
  • Tham số replace có thể được sử dụng để thực hiện thay thế văn bản trong phụ đề (hữu ích để sửa từ hoặc kiểm duyệt nội dung).
  • Tham số webhook_url là tùy chọn và có thể được sử dụng để nhận thông báo khi quá trình thêm phụ đề hoàn tất.
  • Tham số id là tùy chọn và có thể được sử dụng để xác định yêu cầu trong phản hồi webhook.
  • Tham số language là tùy chọn và có thể được sử dụng để chỉ định ngôn ngữ của phụ đề cho việc chuyển đổi thành văn bản. Nếu không được cung cấp, ngôn ngữ sẽ được tự động phát hiện.
  • Tham số exclude_time_ranges có thể được sử dụng để chỉ định các khoảng thời gian cần loại trừ khỏi việc thêm phụ đề.

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

  • Cung cấp video_url không hợp lệ hoặc không thể truy cập.
  • Yêu cầu font không có sẵn trong đối tượng settings.
  • Vượt quá độ dài hàng đợi tối đa, dẫn đến lỗi 429 Too Many Requests.

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

  • Xác thực tham số video_url trước khi gửi yêu cầu để đảm bảo nó trỏ đến tệp video hợp lệ và có thể truy cập.
  • Sử dụng tham số webhook_url để nhận thông báo về quá trình thêm phụ đề, thay vì kiểm tra API để cập nhật.
  • Cung cấp các giá trị id mô tả và có ý nghĩa để dễ dàng xác định yêu cầu trong nhật ký và phản hồi.
  • Sử dụng tham số replace một cách hợp lý để tránh thay thế văn bản không mong muốn trong phụ đề.
  • Cân nhắc lưu cache các tệp video đã thêm phụ đề cho các video được yêu cầu thường xuyên để cải thiện hiệu suất và giảm thời gian xử lý.

Giá cả

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

Chi phí cố định bất kể độ dài video 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
}