Tài liệu API Endpoint Tải xuống phương tiện

Giá cả

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

Tổng quan

Endpoint https://api.revidapi.com/paid/media/download cung cấp giao diện mạnh mẽ để tải xuống nội dung phương tiện từ các nguồn trực tuyến khác nhau bằng thư viện yt-dlp. Endpoint này là một phần của dịch vụ phương tiện v1 trong cấu trúc API, cho phép người dùng tải xuống video, trích xuất âm thanh, và lấy hình thu nhỏ và phụ đề từ các nền tảng được hỗ trợ. Endpoint xử lý xác thực, xác thực yêu cầu, và đưa tác vụ vào hàng đợi để xử lý, phù hợp để xử lý việc tải xuống phương tiện tốn tài nguyên mà không chặn luồng ứng dụng chính. Tutorials RevidAPI

Endpoint

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

Yêu cầu

Headers

x-api-key: Bắt buộc để xác thực (được xử lý bởi decorator @authenticate)

Tham số Body

Tham số bắt buộc

Tham số	Kiểu	Mô tả
`media_url`	string (định dạng URI)	URL của phương tiện cần tải xuống

Tham số tùy chọn

Tham số	Kiểu	Mô tả
`webhook_url`	string (định dạng URI)	URL để nhận kết quả khi xử lý hoàn tất
`id`	string	Mã định danh tùy chỉnh để theo dõi yêu cầu
`cookie`	string	Đường dẫn đến tệp cookie, URL đến tệp cookie, hoặc chuỗi cookie ở định dạng Netscape
`cloud_upload`	boolean	Khi true (mặc định), phương tiện đã tải xuống sẽ được tải lên cloud storage và URL cloud sẽ được trả về. Khi false, URL tải xuống trực tiếp của phương tiện sẽ được trả về thay thế.

Tùy chọn định dạng (Tùy chọn)

"format": {
  "quality": "string",     // Chỉ định chất lượng (ví dụ: "best")
  "format_id": "string",   // ID định dạng cụ thể
  "resolution": "string",  // Chỉ định độ phân giải (ví dụ: "720p")
  "video_codec": "string", // Tùy chọn codec video
  "audio_codec": "string"  // Tùy chọn codec âm thanh
}

Tùy chọn âm thanh (Tùy chọn)

"audio": {
  "extract": boolean,      // Có trích xuất âm thanh hay không
  "format": "string",      // Định dạng âm thanh (ví dụ: "mp3", "m4a")
  "quality": "string"      // Chỉ định chất lượng âm thanh
}

Tùy chọn hình thu nhỏ (Tùy chọn)

"thumbnails": {
  "download": boolean,     // Có tải xuống hình thu nhỏ hay không
  "download_all": boolean, // Có tải xuống tất cả hình thu nhỏ có sẵn hay không
  "formats": ["string"],   // Mảng các định dạng hình thu nhỏ để tải xuống
  "convert": boolean,      // Có chuyển đổi hình thu nhỏ hay không
  "embed_in_audio": boolean // Có nhúng hình thu nhỏ vào tệp âm thanh hay không
}

Tùy chọn phụ đề (Tùy chọn)

"subtitles": {
  "download": boolean,     // Có tải xuống phụ đề hay không
  "languages": ["string"], // Mảng mã ngôn ngữ cho phụ đề
  "format": "string",      // Định dạng phụ đề để tải xuống (ví dụ: 'srt', 'vtt', 'json3')
  "cloud_upload": boolean  // Có tải lên phụ đề lên cloud storage hay không (mặc định là true)
}

Tùy chọn tải xuống (Tùy chọn)

"download": {
  "max_filesize": integer, // Kích thước tệp tối đa tính bằng byte
  "rate_limit": "string",  // Giới hạn tốc độ tải xuống (ví dụ: "50K")
  "retries": integer       // Số lần thử lại tải xuống
}

Ví dụ yêu cầu

{
  "media_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "webhook_url": "https://example.com/webhook",
  "id": "custom-request-123",
  "cookie": "# Netscape HTTP Cookie File\n.youtube.com\tTRUE\t/\tFALSE\t0\tCONSENT\tYES+cb",
  "cloud_upload": true,
  "format": {
    "quality": "best",
    "resolution": "720p"
  },
  "audio": {
    "extract": true,
    "format": "mp3"
  },
  "thumbnails": {
    "download": true
  },
  "subtitles": {
    "download": true,
    "languages": ["en", "es-419"],
    "format": "srt",
    "cloud_upload": true
  }
}

Ví dụ lệnh cURL

curl -X POST \
  https://api.revidapi.com/paid/media/download \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: your-api-key-here' \
  -d '{
    "media_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "webhook_url": "https://example.com/webhook",
    "id": "custom-request-123",
    "cookie": "# Netscape HTTP Cookie File\n.youtube.com\tTRUE\t/\tFALSE\t0\tCONSENT\tYES+cb",
    "cloud_upload": true,
    "format": {
      "quality": "best",
      "resolution": "720p"
    },
    "audio": {
      "extract": true,
      "format": "mp3"
    },
    "thumbnails": {
      "download": true
    },
    "subtitles": {
      "download": true,
      "languages": ["en", "es-419"],
      "format": "srt",
      "cloud_upload": true
    }
  }'

Phản hồi

Phản hồi ngay lập tức (Khi sử dụng Webhook)

Khi cung cấp webhook URL, API sẽ đưa tác vụ vào hàng đợi và trả về phản hồi ngay lập tức với mã trạng thái 202:

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

Phản hồi thành công (Khi không sử dụng Webhook hoặc khi Webhook được gọi)

{
  "code": 200,
  "id": "custom-request-123",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "response": {
    "media": {
      "media_url": "https://storage.example.com/media/video-123.mp4",
      "title": "Never Gonna Give You Up",
      "format_id": "22",
      "ext": "mp4",
      "resolution": "720p",
      "filesize": 12345678,
      "width": 1280,
      "height": 720,
      "fps": 30,
      "video_codec": "avc1.4d401f",
      "audio_codec": "mp4a.40.2",
      "upload_date": "20090325",
      "duration": 212,
      "view_count": 1234567890,
      "uploader": "Rick Astley",
      "uploader_id": "RickAstleyVEVO",
      "description": "Official music video for Rick Astley - Never Gonna Give You Up"
    },
    "thumbnails": [
      {
        "id": "default",
        "image_url": "https://storage.example.com/media/thumbnail-123.jpg",
        "width": 1280,
        "height": 720,
        "original_format": "jpg",
        "converted": false
      }
    ]
  },
  "message": "success",
  "pid": 12345,
  "queue_id": 67890,
  "run_time": 5.123,
  "queue_time": 0.456,
  "total_time": 5.579,
  "queue_length": 2,
  "build_number": "1.0.123"
}

Phản hồi lỗi

Yêu cầu không hợp lệ (400)

{
  "code": 400,
  "id": "custom-request-123",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Invalid request: 'media_url' is a required property",
  "pid": 12345,
  "queue_id": 67890,
  "queue_length": 2,
  "build_number": "1.0.123"
}

Lỗi xác thực (401)

{
  "code": 401,
  "message": "Invalid API key",
  "build_number": "1.0.123"
}

Hàng đợi đầy (429)

{
  "code": 429,
  "id": "custom-request-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.123"
}

Lỗi server (500)

{
  "code": 500,
  "id": "custom-request-123",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Error during download process - HTTP Error 403: Forbidden",
  "pid": 12345,
  "queue_id": 67890,
  "queue_length": 2,
  "build_number": "1.0.123"
}

Xử lý lỗi

Endpoint xử lý các kịch bản lỗi khác nhau:

Thiếu tham số bắt buộc: Trả về mã trạng thái 400 với chi tiết về tham số bị thiếu
Định dạng tham số không hợp lệ: Trả về mã trạng thái 400 nếu tham số không khớp với định dạng mong đợi
Lỗi xác thực: Trả về mã trạng thái 401 nếu API key không hợp lệ hoặc thiếu
Giới hạn hàng đợi: Trả về mã trạng thái 429 nếu hàng đợi tác vụ đầy (khi MAX_QUEUE_LENGTH được đặt)
Lỗi tải xuống: Trả về mã trạng thái 500 với chi tiết về lỗi tải xuống
Lỗi nguồn phương tiện: Trả về mã trạng thái 500 nếu nguồn phương tiện không khả dụng hoặc bị hạn chế

Ghi chú sử dụng

Xử lý Webhook:
Khi cung cấp webhook_url, yêu cầu sẽ được đưa vào hàng đợi và xử lý không đồng bộ
Không có webhook_url, yêu cầu sẽ được xử lý đồng bộ, điều này có thể dẫn đến thời gian phản hồi lâu hơn
Lựa chọn định dạng:
Các tùy chọn format cho phép kiểm soát chi tiết chất lượng phương tiện đã tải xuống
Khi nhiều tùy chọn định dạng được chỉ định, chúng được kết hợp với dấu phân cách '+'
Trích xuất âm thanh:
Đặt audio.extract thành true sẽ trích xuất âm thanh từ phương tiện
Chỉ định audio.format để kiểm soát định dạng âm thanh đầu ra (ví dụ: "mp3", "m4a")
Xử lý hình thu nhỏ:
Khi thumbnails.download là true, API sẽ tải xuống và cung cấp URL cho hình thu nhỏ
Sử dụng thumbnails.download_all để lấy tất cả hình thu nhỏ có sẵn
Giới hạn tốc độ:
Sử dụng download.rate_limit để kiểm soát tốc độ tải xuống (ví dụ: "50K" cho 50 KB/s)
Điều này có thể giúp ngăn chặn việc IP bị chặn từ một số nguồn phương tiện

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

Nội dung bị hạn chế địa lý: Một số phương tiện có thể không khả dụng ở một số khu vực
Giới hạn tốc độ: Nguồn phương tiện có thể giới hạn tốc độ hoặc chặn tải xuống thường xuyên
Tải xuống tệp lớn: Tệp rất lớn có thể bị timeout trong quá trình tải xuống
Khả năng sử dụng định dạng: Không phải tất cả định dạng được yêu cầu có thể có sẵn cho tất cả nguồn phương tiện
Lỗi Webhook: Nếu URL webhook không thể truy cập, bạn sẽ không nhận được kết quả cuối cùng
Hàng đợi tràn: Yêu cầu có thể bị từ chối nếu hàng đợi xử lý đầy

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

Sử dụng Webhooks cho tải xuống lớn: Luôn sử dụng webhooks cho các tải xuống có thể lớn hoặc chậm để tránh vấn đề timeout
Chỉ định ràng buộc định dạng: Hãy cụ thể về yêu cầu định dạng để tránh tải xuống không cần thiết lớn
Xử lý hình thu nhỏ riêng biệt: Để hiệu quả, chỉ yêu cầu hình thu nhỏ khi cần
Triển khai logic thử lại: Triển khai logic thử lại ở phía máy khách để xử lý các lỗi tạm thời
Giám sát độ dài hàng đợi: Kiểm tra queue_length trong phản hồi để đánh giá tải hệ thống
Sử dụng giới hạn tốc độ hợp lý: Đặt giá trị download.rate_limit phù hợp để tránh bị chặn bởi nguồn phương tiện
Xác thực URL phương tiện: Đảm bảo URL phương tiện hợp lệ và có thể truy cập trước khi gửi
Lưu trữ phương tiện đã tải xuống: URL cloud được cung cấp trong phản hồi có thể có thời gian hết hạn, vì vậy hãy tải xuống và lưu trữ phương tiện quan trọng ngay lập tức

Giá cả

5 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
}