docs/video/cut.md

Video Cut Endpoint

1. Overview

The /v1/video/cut endpoint is part of the Video API and allows users to cut specified segments from a video file with optional encoding settings. This endpoint fits into the overall API structure as a part of the version 1 (v1) routes, specifically under the video category.

2. Endpoint

POST /v1/video/cut

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 cut.
• cuts (required, array of objects): An array of cut segments, where each object has the following properties:
  • start (required, string): The start time of the cut segment in the format hh:mm:ss.ms.
  • end (required, string): The end time of the cut segment in the format hh:mm:ss.ms.
• video_codec (optional, string): The video codec to use for encoding the output video. Default is libx264.
• video_preset (optional, string): The video preset to use for encoding the output video. 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 output video. Default is aac.
• audio_bitrate (optional, string): The audio bitrate to use for encoding the output video. Default is 128k.
• webhook_url (optional, string): The URL to receive a webhook notification when the job is completed.
• id (optional, string): A unique identifier for the request.

Example Request

{
  "video_url": "https://example.com/video.mp4",
  "cuts": [
    {
      "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.example.com/v1/video/cut \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "video_url": "https://example.com/video.mp4",
    "cuts": [
      {
        "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 response follows the general response format defined in the main application context (app.py). Here's an example of a successful response:

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

The response field contains the URL of the processed video file.

Error Responses

• 400 Bad Request

  {
    "code": 400,
    "message": "Invalid request payload"
  }
  

  This error occurs when the request payload is missing required fields or contains invalid data.

• 401 Unauthorized

  {
    "code": 401,
    "message": "Invalid API key"
  }
  

  This error occurs when the provided x-api-key header is missing or invalid.

• 429 Too Many Requests

  {
    "code": 429,
    "id": "unique-request-id",
    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "message": "MAX_QUEUE_LENGTH (100) reached",
    "pid": 12345,
    "queue_id": 6789,
    "queue_length": 100,
    "build_number": "1.0.0"
  }
  

  This error occurs when the maximum queue length has been reached, and the request cannot be processed immediately.

• 500 Internal Server Error

  {
    "code": 500,
    "message": "An error occurred during video processing"
  }
  

  This error occurs when an unexpected error occurs during the video processing or encoding.

5. Error Handling

The endpoint handles the following common errors:

• Missing or invalid request parameters: If any required parameters are missing or invalid, the endpoint returns a 400 Bad Request error with an appropriate error message.
• Invalid API key: If the provided x-api-key header is missing or invalid, the endpoint returns a 401 Unauthorized error.
• Queue limit reached: If the maximum queue length has been reached, the endpoint returns a 429 Too Many Requests error with the current queue length and the maximum queue length.
• Unexpected errors during video processing: If an unexpected error occurs during the video processing or encoding, the endpoint returns a 500 Internal Server Error with a generic error message.

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

6. Usage Notes

• The video_url parameter must be a valid URL that points to a video file accessible by the server.
• The cuts parameter must be an array of objects, where each object represents a cut segment with a start and end time in the format hh:mm:ss.ms.
• The optional encoding parameters (video_codec, video_preset, video_crf, audio_codec, audio_bitrate) allow you to customize the encoding settings for the output video file.
• If the webhook_url parameter is provided, the server will send a webhook notification to the specified URL when the job is completed.
• The id parameter can be used to associate the request with a unique identifier for tracking purposes.

7. Common Issues

• Providing an invalid or inaccessible video_url.
• Specifying overlapping or invalid cut segments in the cuts parameter.
• Providing invalid encoding settings that are not supported by the server.
• Reaching the maximum queue length, which can cause requests to be rejected with 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 and accessible video file.
• Ensure that the cut segments in the cuts parameter are correctly formatted and do not overlap or exceed the duration of the video.
• Use the optional encoding parameters judiciously, as they can impact the processing time and output video quality.
• Implement retry mechanisms for handling 429 Too Many Requests errors, as the queue length may fluctuate over time.
• Monitor the webhook notifications or poll the server for job status updates to track the progress of long-running jobs.