Bỏ qua

Endpoint Tạo phụ đề ASS

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.

1. Tổng quan

Endpoint https://api.revidapi.com/paid/media/generate/ass là một phần của Media API và chịu trách nhiệm tạo tệp phụ đề ASS (Advanced SubStation Alpha) từ tệp phương tiện (thường là video hoặc âm thanh). Nó chấp nhận URL phương tiện và các tùy chọn tạo kiểu khác nhau cho phụ đề.

2. Endpoint

URL: https://api.revidapi.com/paid/media/generate/ass 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:

Lưu ý: canvas_width và canvas_height được khuyến nghị cho tệp âm thanh (ví dụ: MP3) để kiểm soát kích thước canvas phụ đề.

  • media_url (string, bắt buộc): URL của tệp phương tiện (video hoặc âm thanh) để tạo phụ đề.
  • canvas_width (integer, tùy chọn): Chiều rộng canvas phụ đề tính bằng pixel.
  • canvas_height (integer, tùy chọn): Chiều cao canvas phụ đề tính bằng pixel.
  • 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ụ đề.
  • exclude_time_ranges (mảng, tùy chọn): Danh sách các khoảng thời gian cần bỏ qua khi tạo 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.
  • language (string, tùy chọn): Mã ngôn ngữ cho phụ đề (ví dụ: "en", "fr"). Mặc định là "auto".
  • webhook_url (string, tùy chọn): URL để nhận thông báo webhook khi quá trình tạo phụ đề hoàn tất.
  • id (string, tùy chọn): Mã định danh cho yêu cầu.

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: Tạo phụ đề tự động cơ bản

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

Ví dụ 2: Tạo kiểu tùy chỉnh

{
    "media_url": "https://example.com/video.mp4",
    "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

{
    "media_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: Loại trừ khoảng thời gian khỏi việc tạo phụ đề

{
    "media_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" }
    ]
}

Ví dụ 5: Tạo phụ đề cho tệp MP3 (âm thanh)

{
    "canvas_width": 1280,
    "canvas_height": 720,
    "media_url": "https://example.com/audio.mp3",
    "settings": {
        "style": "classic",
        "font_family": "Arial",
        "font_size": 32,
        "line_color": "#FFFFFF",
        "outline_color": "#000000"
    }
}

curl -X POST \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
        "media_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/media/generate/ass

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 phụ đề ASS đã tạo.
  • 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/generated-subtitles.ass",
    "message": "success",
    "pid": 12345,
    "queue_id": 140682639937472,
    "run_time": 2.345,
    "queue_time": 0.010,
    "total_time": 2.355,
    "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 subtitle generation 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 tạo 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ố media_url phải là URL hợp lệ trỏ đến tệp video hoặc âm thanh.
  • 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 tạo 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 tạo phụ đề.
  • Nếu cung cấp canvas_width hoặc canvas_height, cả hai đều phải được cung cấp và phải lớn hơn 0.

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

  • Cung cấp media_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.
  • Sử dụng endpoint này với tệp chỉ có âm thanh (ví dụ: MP3) và không cung cấp cả canvas_width và canvas_height. Đối với tệp âm thanh, bạn phải chỉ định cả hai kích thước để tạo tệp phụ đề ASS hợp lệ.
  • 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ố media_url trước khi gửi yêu cầu để đảm bảo nó trỏ đến tệp phương tiện 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 tạo 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 ASS đã tạo cho phương tiện đượ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ả

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
}