Video Split Endpoint

1. Overview

The https://api.revidapi.com/paid/video/split endpoint is part of the Video API and is used to split a video file into multiple segments based on specified start and end times.

2. Endpoint

URL Path: https://api.revidapi.com/paid/video/split HTTP Method: POST

3. Request

Headers

x-api-key (required): The API key for authentication.

Body Parameters

The request body must be a JSON object with the following properties:

video_url (required, string): The URL of the video file to be split.
splits (required, array of objects): An array of objects specifying the start and end times for each split. Each object must have the following properties:
start (required, string): The start time of the split in the format hh:mm:ss.ms.
end (required, string): The end time of the split in the format hh:mm:ss.ms.
video_codec (optional, string): The video codec to use for encoding the split videos. Default is libx264.
video_preset (optional, string): The video preset to use for encoding the split videos. Default is medium.
video_crf (optional, number): The Constant Rate Factor (CRF) value for video encoding. Must be between 0 and 51. Default is 23.
audio_codec (optional, string): The audio codec to use for encoding the split videos. Default is aac.
audio_bitrate (optional, string): The audio bitrate to use for encoding the split videos. Default is 128k.
webhook_url (optional, string): The URL to receive a webhook notification when the split operation is complete.
id (optional, string): A unique identifier for the request.

Example Request

{
  "video_url": "https://example.com/video.mp4",
  "splits": [
    {
      "start": "00:00:10.000",
      "end": "00:00:20.000"
    },
    {
      "start": "00:00:30.000",
      "end": "00:00:40.000"
    }
  ],
  "video_codec": "libx264",
  "video_preset": "medium",
  "video_crf": 23,
  "audio_codec": "aac",
  "audio_bitrate": "128k",
  "webhook_url": "https://example.com/webhook",
  "id": "unique-request-id"
}

curl -X POST \
  https://api.revidapi.com/paid/video/split \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "video_url": "https://example.com/video.mp4",
    "splits": [
      {
        "start": "00:00:10.000",
        "end": "00:00:20.000"
      },
      {
        "start": "00:00:30.000",
        "end": "00:00:40.000"
      }
    ],
    "video_codec": "libx264",
    "video_preset": "medium",
    "video_crf": 23,
    "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 format specified in app.py. Here's an example:

{
  "endpoint": "/v1/video/split",
  "code": 200,
  "id": "unique-request-id",
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  "response": [
    {
      "file_url": "https://example.com/split-1.mp4"
    },
    {
      "file_url": "https://example.com/split-2.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"
}

The response field contains an array of objects, each representing a split video file. Each object has a file_url property containing the URL of the split video file.

Error Responses

400 Bad Request: Returned when the request payload is missing or invalid.
401 Unauthorized: Returned when the x-api-key header is missing or invalid.
429 Too Many Requests: Returned when the maximum queue length has been reached.
500 Internal Server Error: Returned when an unexpected error occurs during the video split process.

Example error response:

{
  "code": 400,
  "id": "unique-request-id",
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  "message": "Invalid request payload: 'splits' is a required property",
  "pid": 12345,
  "queue_id": 6789,
  "queue_length": 2,
  "build_number": "1.0.0"
}

5. Error Handling

The endpoint handles the following common errors:

Missing or invalid request parameters: Returns a 400 Bad Request error with a descriptive error message.
Authentication failure: Returns a 401 Unauthorized error if the x-api-key header is missing or invalid.
Queue length exceeded: Returns a 429 Too Many Requests error if the maximum queue length has been reached.
Unexpected exceptions: Returns a 500 Internal Server Error with the exception message.

The main application context (app.py) also includes error handling for queue length limits and webhook notifications.

6. Usage Notes

The video_url parameter must be a valid URL pointing to a video file.
The splits array must contain at least one object specifying the start and end times for a split.
The start and end times must be in the format hh:mm:ss.ms (hours:minutes:seconds.milliseconds).
The video_codec, video_preset, video_crf, audio_codec, and audio_bitrate parameters are optional and can be used to customize the encoding settings for the split videos.
If the webhook_url parameter is provided, a webhook notification will be sent to the specified URL when the split operation is complete.
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 overlapping or invalid start and end times in the splits array.
Exceeding the maximum queue length, which can result in a 429 Too Many Requests error.

8. Best Practices

Validate the video_url parameter before sending the request to ensure it points to a valid video file.
Ensure that the start and end times in the splits array are correctly formatted and do not overlap.
Consider using the webhook_url parameter to receive notifications about the completion of the split operation, especially for long-running or asynchronous requests.
Implement retry mechanisms and error handling in your client application to handle potential errors and failures.
Monitor the queue length and adjust the MAX_QUEUE_LENGTH environment variable as needed to prevent excessive queuing and potential timeouts.