Spaces:
Runtime error
Runtime error
File size: 5,299 Bytes
4b12e15 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 | # Video Thumbnail Generation API
## Overview
The `/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. The endpoint processes the request asynchronously using a queue system, uploads the generated thumbnail to cloud storage, and returns the URL of the uploaded image.
## Endpoint
- **URL**: `/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
```json
{
"video_url": "https://example.com/video.mp4",
"second": 30,
"webhook_url": "https://your-service.com/webhook",
"id": "custom-request-123"
}
```
### Example cURL Command
```bash
curl -X POST \
https://api.example.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:
```json
{
"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:
```json
{
"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)
```json
{
"code": 400,
"message": "Invalid request: 'video_url' is a required property",
"job_id": "550e8400-e29b-41d4-a716-446655440000"
}
```
#### Queue Full (Status Code: 429)
```json
{
"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)
```json
{
"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. |