Video Thumbnail Generation API¶

Pricing¶

35 credits per request

Fixed cost regardless of video length or number of thumbnails.

Overview¶

The https://api.revidapi.com/paid/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://api.revidapi.com/paid/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://api.revidapi.com/paid/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¶

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

Common Issues¶

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

Best Practices¶

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

Get Job Status¶

After submitting a job, you can check its status using the job_id returned in the response.