Video Thumbnail Generation API

Pricing

35 credits per request

Fixed cost regardless of video length or number of thumbnails.

Overview

The https://revidapi.com/v1/video/thumbnail endpoint allows users to extract a thumbnail image from a specific timestamp in a video. This endpoint is part of the video processing capabilities of the API, which includes other features like video concatenation and captioning. RevidAPI Tutorials

Endpoint

• URL: https://revidapi.com/v1/video/thumbnail
• Method: POST

Request

Headers

• x-api-key: Required. Your API authentication key.

Body Parameters

Parameter	Type	Required	Description
video_url	string (URI format)	Yes	URL of the video from which to extract the thumbnail
second	number (minimum: 0)	No	Timestamp in seconds at which to extract the thumbnail (defaults to 0)
webhook_url	string (URI format)	No	URL to receive the processing result asynchronously
id	string	No	Custom identifier for tracking the request

Example Request

{
  "video_url": "https://example.com/video.mp4",
  "second": 30,
  "webhook_url": "https://your-service.com/webhook",
  "id": "custom-request-123"
}

Example cURL Command

curl -X POST \
  https://revidapi.com/v1/video/thumbnail \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: your-api-key' \
  -d '{
    "video_url": "https://example.com/video.mp4",
    "second": 30,
    "webhook_url": "https://your-service.com/webhook",
    "id": "custom-request-123"
  }'

Response

Immediate Response (Status Code: 202)

When a webhook URL is provided, the API immediately returns a 202 Accepted response and processes the request asynchronously:

{
  "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": 1,
  "build_number": "1.0.0"
}

Success Response (Status Code: 200)

When no webhook URL is provided or when the webhook is called after processing:

{
  "code": 200,
  "id": "custom-request-123",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "response": "https://storage.example.com/thumbnails/video-thumbnail-123.jpg",
  "message": "success",
  "run_time": 1.234,
  "queue_time": 0.567,
  "total_time": 1.801,
  "pid": 12345,
  "queue_id": 67890,
  "queue_length": 0,
  "build_number": "1.0.0"
}

Error Responses

Invalid Request (Status Code: 400)

{
  "code": 400,
  "message": "Invalid request: 'video_url' is a required property",
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Queue Full (Status Code: 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.0"
}

Server Error (Status Code: 500)

{
  "code": 500,
  "id": "custom-request-123",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Failed to download video from provided URL",
  "pid": 12345,
  "queue_id": 67890,
  "queue_length": 0,
  "build_number": "1.0.0"
}

Error Handling

The endpoint handles various error scenarios:

• Missing Required Parameters: Returns a 400 error if video_url is missing.
• Invalid Parameter Format: Returns a 400 error if parameters don't match the expected format (e.g., invalid URLs).
• Queue Capacity: Returns a 429 error if the processing queue is full.
• Processing Errors: Returns a 500 error if there are issues during thumbnail extraction or upload.

Usage Notes

1. Asynchronous Processing: For long-running operations, provide a webhook_url to receive the result asynchronously.
2. Timestamp Selection: Choose an appropriate second value to capture a meaningful frame from the video.
3. Request Tracking: Use the id parameter to track your requests across your systems.
4. Queue Management: The API uses a queue system with configurable maximum length (set by the MAX_QUEUE_LENGTH environment variable).

Common Issues

1. Inaccessible Video URLs: Ensure the video URL is publicly accessible or has proper authentication.
2. Invalid Timestamp: If the specified second exceeds the video duration, the API may use the last frame or return an error.
3. Webhook Failures: If your webhook endpoint is unavailable, you won't receive the processing result.
4. Large Videos: Processing very large videos may take longer and could time out.

Best Practices

1. Use Webhooks for Long Videos: Always use webhooks when processing large videos to avoid HTTP timeout issues.
2. Optimize Thumbnail Selection: Choose meaningful timestamps for thumbnails (e.g., after intro sequences).
3. Error Handling: Implement proper error handling in your application to manage API errors gracefully.
4. Rate Limiting: Monitor the queue length in responses to avoid overwhelming the service.
5. Idempotent Requests: Use the id parameter to make requests idempotent and avoid duplicate processing.

Best Practices

1. Use Webhooks for Long Videos: Always use webhooks when processing large videos to avoid HTTP timeout issues.
2. Optimize Thumbnail Selection: Choose meaningful timestamps for thumbnails (e.g., after intro sequences).
3. Error Handling: Implement proper error handling in your application to manage API errors gracefully.
4. Rate Limiting: Monitor the queue length in responses to avoid overwhelming the service.
5. Idempotent Requests: Use the id parameter to make requests idempotent and avoid duplicate processing.

---

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://revidapi.com/v1/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://revidapi.com/v1/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
}