Chuyển đổi hình ảnh sang video

1. Tổng quan

Endpoint https://api.revidapi.com/paid/image/convert/video là một phần của ứng dụng Flask API và chịu trách nhiệm chuyển đổi hình ảnh thành tệp video.

Tutorials RevidAPI

2. Endpoint

URL Path: https://api.revidapi.com/paid/image/convert/video HTTP 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 ở định dạng JSON và nên bao gồm các tham số sau:

Tham số	Kiểu	Bắt buộc	Mô tả
`image_url`	string	Có	URL của hình ảnh cần chuyển đổi thành video.
`length`	number	Không	Độ dài mong muốn của video tính bằng giây (mặc định: 5).
`frame_rate`	integer	Không	Tốc độ khung hình của video đầu ra (mặc định: 30).
`zoom_speed`	number	Không	Tốc độ của hiệu ứng zoom (0-100, mặc định: 3).
`webhook_url`	string	Không	URL để nhận thông báo webhook khi hoàn tất.
`id`	string	Không	Mã định danh tùy chọn cho yêu cầu.

Decorator validate_payload trong module routes.v1.image.convert.image_to_video áp dụng schema JSON sau cho body yêu cầu:

{
    "type": "object",
    "properties": {
        "image_url": {"type": "string", "format": "uri"},
        "length": {"type": "number", "minimum": 1, "maximum": 60},
        "frame_rate": {"type": "integer", "minimum": 15, "maximum": 60},
        "zoom_speed": {"type": "number", "minimum": 0, "maximum": 100},
        "webhook_url": {"type": "string", "format": "uri"},
        "id": {"type": "string"}
    },
    "required": ["image_url"],
    "additionalProperties": false
}

Ví dụ yêu cầu

{
    "image_url": "https://example.com/image.jpg",
    "length": 10,
    "frame_rate": 24,
    "zoom_speed": 5,
    "webhook_url": "https://example.com/webhook",
    "id": "request-123"
}

curl -X POST \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"image_url": "https://example.com/image.jpg", "length": 10, "frame_rate": 24, "zoom_speed": 5, "webhook_url": "https://example.com/webhook", "id": "request-123"}' \
     https://api.revidapi.com/paid/image/convert/video

4. Phản hồi

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

Khi xử lý thành công, endpoint trả về phản hồi JSON với cấu trúc sau:

{
    "code": 200,
    "id": "request-123",
    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "response": "https://cloud-storage.example.com/converted-video.mp4",
    "message": "success",
    "run_time": 2.345,
    "queue_time": 0.123,
    "total_time": 2.468,
    "pid": 12345,
    "queue_id": 1234567890,
    "queue_length": 0,
    "build_number": "1.0.0"
}

Trường response chứa URL của tệp video đã chuyển đổi được tải lên cloud storage.

Phản hồi lỗi

429 Too Many Requests

Nếu đạt đến độ dài hàng đợi tối đa, endpoint trả về phản hồi 429 Too Many Requests:

{
    "code": 429,
    "id": "request-123",
    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "message": "MAX_QUEUE_LENGTH (10) reached",
    "pid": 12345,
    "queue_id": 1234567890,
    "queue_length": 10,
    "build_number": "1.0.0"
}

500 Internal Server Error

Nếu có ngoại lệ xảy ra trong quá trình chuyển đổi hình ảnh sang video, endpoint trả về phản hồi 500 Internal Server Error:

{
    "code": 500,
    "id": "request-123",
    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "message": "Error message describing the exception",
    "pid": 12345,
    "queue_id": 1234567890,
    "queue_length": 0,
    "build_number": "1.0.0"
}

5. Xử lý lỗi

Endpoint xử lý các loại lỗi sau:

Thiếu hoặc tham số không hợp lệ: Nếu body yêu cầu thiếu tham số bắt buộc hoặc chứa giá trị tham số không hợp lệ, decorator validate_payload sẽ trả về phản hồi 400 Bad Request với thông báo lỗi mô tả.
Vượt quá độ dài hàng đợi: Nếu đạt đến độ dài hàng đợi tối đa và tham số bypass_queue được đặt thành False, endpoint trả về phản hồi 429 Too Many Requests.
Ngoại lệ trong quá trình xử lý: Nếu có ngoại lệ xảy ra trong quá trình chuyển đổi hình ảnh sang video, endpoint trả về phản hồi 500 Internal Server Error với thông báo lỗi.

6. Ghi chú sử dụng

Tham số image_url phải là URL hợp lệ trỏ đến tệp hình ảnh.
Tham số length chỉ định thời lượng của video đầu ra tính bằng giây và phải nằm trong khoảng từ 1 đến 60.
Tham số frame_rate chỉ định tốc độ khung hình của video đầu ra và phải nằm trong khoảng từ 15 đến 60.
Tham số zoom_speed điều khiển tốc độ của hiệu ứng zoom và phải nằm trong khoảng từ 0 đến 100.
Tham số webhook_url là tùy chọn và có thể được sử dụng để nhận thông báo khi chuyển đổi 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.

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

Cung cấp image_url không hợp lệ hoặc không thể truy cập sẽ dẫn đến lỗi trong quá trình xử lý.
Chỉ định giá trị tham số không hợp lệ ngoài phạm vi cho phép sẽ dẫn đến phản hồi 400 Bad Request.
Nếu đạt đến độ dài hàng đợi tối đa và tham số bypass_queue được đặt thành False, yêu cầu sẽ bị từ chối với phản hồi 429 Too Many Requests.

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

Xác thực tham số image_url ở phía máy khách trước khi gửi yêu cầu để đảm bảo nó trỏ đến tệp hình ảnh hợp lệ và có thể truy cập.
Sử dụng tham số webhook_url để nhận thông báo về việc hoàn tất quá trình chuyển đổi, thay vì kiểm tra API nhiều lần.
Cung cấp tham số id để dễ dàng xác định và theo dõi yêu cầu trong nhật ký hoặc thông báo.
Cân nhắc đặt tham số bypass_queue thành True cho các yêu cầu nhạy cảm về thời gian để bỏ qua hàng đợi và xử lý yêu cầu ngay lập tức.

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/image/convert/video",
      "code": 200,
      "id": "request-123",
      "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
      "response": "https://cloud-storage.example.com/converted-video.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
}