Spaces:
Runtime error
Runtime error
File size: 5,629 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 | # Video Trim Endpoint
## 1. Overview
The `/v1/video/trim` endpoint is part of the Video API and allows users to trim a video by removing specified portions from the beginning and/or end. It also provides optional encoding settings to control the output video quality. This endpoint fits into the overall API structure as a part of the version 1 (`v1`) routes, specifically under the `video` category.
## 2. Endpoint
**URL Path:** `/v1/video/trim`
**HTTP Method:** `POST`
## 3. Request
### Headers
- `x-api-key` (required): The API key for authentication.
### Body Parameters
- `video_url` (required, string): The URL of the video file to be trimmed.
- `start` (optional, string): The start time for trimming in the format `hh:mm:ss` or `mm:ss`.
- `end` (optional, string): The end time for trimming in the format `hh:mm:ss` or `mm:ss`.
- `video_codec` (optional, string): The video codec to be used for encoding the output video. Default is `libx264`.
- `video_preset` (optional, string): The video preset to be used for encoding the output video. Default is `medium`.
- `video_crf` (optional, number): The Constant Rate Factor (CRF) value for video encoding, ranging from 0 to 51. Default is 23.
- `audio_codec` (optional, string): The audio codec to be used for encoding the output video. Default is `aac`.
- `audio_bitrate` (optional, string): The audio bitrate to be used for encoding the output video. Default is `128k`.
- `webhook_url` (optional, string): The URL to receive a webhook notification upon completion of the task.
- `id` (optional, string): A unique identifier for the request.
The `validate_payload` directive in the routes file ensures that the request payload adheres to the specified schema, which includes the required and optional parameters, their data types, and any additional constraints.
### Example Request
```json
{
"video_url": "https://example.com/video.mp4",
"start": "00:01:00",
"end": "00:03:00",
"video_codec": "libx264",
"video_preset": "faster",
"video_crf": 28,
"audio_codec": "aac",
"audio_bitrate": "128k",
"webhook_url": "https://example.com/webhook",
"id": "unique-request-id"
}
```
```bash
curl -X POST \
https://api.example.com/v1/video/trim \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"video_url": "https://example.com/video.mp4",
"start": "00:01:00",
"end": "00:03:00",
"video_codec": "libx264",
"video_preset": "faster",
"video_crf": 28,
"audio_codec": "aac",
"audio_bitrate": "128k",
"webhook_url": "https://example.com/webhook",
"id": "unique-request-id"
}'
```
## 4. Response
### Success Response
The success response follows the general response structure defined in the `app.py` file. Here's an example:
```json
{
"endpoint": "/v1/video/trim",
"code": 200,
"id": "unique-request-id",
"job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
"response": "https://example.com/trimmed-video.mp4",
"message": "success",
"pid": 12345,
"queue_id": 6789,
"run_time": 5.234,
"queue_time": 0.123,
"total_time": 5.357,
"queue_length": 0,
"build_number": "1.0.0"
}
```
### Error Responses
- **400 Bad Request**: Returned when the request payload is missing or contains invalid parameters.
```json
{
"code": 400,
"message": "Invalid request payload"
}
```
- **401 Unauthorized**: Returned when the `x-api-key` header is missing or invalid.
```json
{
"code": 401,
"message": "Unauthorized"
}
```
- **500 Internal Server Error**: Returned when an unexpected error occurs during the video trimming process.
```json
{
"code": 500,
"message": "An error occurred during the video trimming process"
}
```
## 5. Error Handling
The endpoint handles common errors such as missing or invalid parameters by returning appropriate HTTP status codes and error messages. The `validate_payload` decorator ensures that the request payload adheres to the specified schema, and any violations will result in a 400 Bad Request error.
The main application context (`app.py`) includes error handling for the task queue. If the maximum queue length is reached, the endpoint will return a 429 Too Many Requests error with a corresponding message.
## 6. Usage Notes
- The `start` and `end` parameters are optional, but at least one of them must be provided to perform the trimming operation.
- The `video_codec`, `video_preset`, `video_crf`, `audio_codec`, and `audio_bitrate` parameters are optional and allow users to customize the encoding settings for the output video.
- The `webhook_url` parameter is optional and can be used to receive a notification when the task is completed.
- The `id` parameter is optional and can be used to uniquely identify the request.
## 7. Common Issues
- Providing an invalid or inaccessible `video_url`.
- Specifying invalid or unsupported values for the encoding parameters (`video_codec`, `video_preset`, `video_crf`, `audio_codec`, `audio_bitrate`).
- Encountering issues with the video trimming process due to unsupported video formats or corrupted files.
## 8. Best Practices
- Validate the `video_url` parameter to ensure it points to a valid and accessible video file.
- Use appropriate encoding settings based on the desired output quality and file size requirements.
- Implement error handling and retry mechanisms for failed requests or network issues.
- Monitor the task queue length and adjust the `MAX_QUEUE_LENGTH` value accordingly to prevent overloading the system.
- Implement rate limiting or throttling mechanisms to prevent abuse or excessive requests. |