Skip to content

Video Concatenation Endpoint

Pricing

35 credits per request

Fixed cost regardless of number of videos or total length.

1. Overview

The https://revidapi.com/v1/video/concatenate endpoint is a part of the Video API and is responsible for combining multiple video files into a single video file.

2. Endpoint

URL Path: https://revidapi.com/v1/video/concatenate 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_urls (required, array of objects): An array of video URLs to be concatenated. Each object in the array must have a video_url property (string, URI format) containing the URL of the video file.
  • webhook_url (optional, string, URI format): The URL to which the response should be sent as a webhook.
  • id (optional, string): An identifier for the request.

The validate_payload decorator in the routes file enforces the following JSON schema for the request body:

{
    "type": "object",
    "properties": {
        "video_urls": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "video_url": {"type": "string", "format": "uri"}
                },
                "required": ["video_url"]
            },
            "minItems": 1
        },
        "webhook_url": {"type": "string", "format": "uri"},
        "id": {"type": "string"}
    },
    "required": ["video_urls"],
    "additionalProperties": False
}

Example Request

{
    "video_urls": [
        {"video_url": "https://example.com/video1.mp4"},
        {"video_url": "https://example.com/video2.mp4"},
        {"video_url": "https://example.com/video3.mp4"}
    ],
    "webhook_url": "https://example.com/webhook",
    "id": "request-123"
}

curl -X POST \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
        "video_urls": [
            {"video_url": "https://example.com/video1.mp4"},
            {"video_url": "https://example.com/video2.mp4"},
            {"video_url": "https://example.com/video3.mp4"}
        ],
        "webhook_url": "https://example.com/webhook",
        "id": "request-123"
     }' \
     https://revidapi.com/v1/video/concatenate

4. Response

Success Response

The success response follows the general response format defined in the app.py file. Here's an example:

{
    "endpoint": "/v1/video/concatenate",
    "code": 200,
    "id": "request-123",
    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "response": "https://cloud-storage.example.com/combined-video.mp4",
    "message": "success",
    "pid": 12345,
    "queue_id": 6789,
    "run_time": 10.234,
    "queue_time": 2.345,
    "total_time": 12.579,
    "queue_length": 0,
    "build_number": "1.0.0"
}

The response field contains the URL of the combined video file uploaded to cloud storage.

Error Responses

  • 400 Bad Request: Returned when the request body is missing or invalid.
{
  "code": 400,
  "message": "Invalid request payload"
}
  • 401 Unauthorized: Returned when the x-api-key header is missing or invalid.
{
  "code": 401,
  "message": "Unauthorized"
}
  • 429 Too Many Requests: Returned when the maximum queue length is reached.
{
  "code": 429,
  "id": "request-123",
  "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"
}
  • 500 Internal Server Error: Returned when an unexpected error occurs during the video concatenation process.
{
  "code": 500,
  "message": "An error occurred during video concatenation"
}

5. Error Handling

The endpoint handles the following common errors:

  • Missing or invalid request body: If the request body is missing or does not conform to the expected JSON schema, a 400 Bad Request error is returned.
  • Missing or invalid API key: If the x-api-key header is missing or invalid, a 401 Unauthorized error is returned.
  • Queue length exceeded: If the maximum queue length is reached (determined by the MAX_QUEUE_LENGTH environment variable), a 429 Too Many Requests error is returned.
  • Unexpected errors during video concatenation: If an unexpected error occurs during the video concatenation process, a 500 Internal Server Error is returned with the error message.

The main application context (app.py) also includes error handling for the task queue. If the queue length exceeds the MAX_QUEUE_LENGTH limit, the request is rejected with a 429 Too Many Requests error.

6. Usage Notes

  • The video files to be concatenated must be accessible via the provided URLs.
  • The order of the video files in the video_urls array determines the order in which they will be concatenated.
  • If the webhook_url parameter is provided, the response will be sent as a webhook to the specified URL.
  • The id parameter can be used to identify the request in the response.

7. Common Issues

  • Providing invalid or inaccessible video URLs.
  • Exceeding the maximum queue length, which can lead to requests being rejected with a 429 Too Many Requests error.
  • Encountering unexpected errors during the video concatenation process, which can result in a 500 Internal Server Error.

8. Best Practices

  • Validate the video URLs before sending the request to ensure they are accessible and in the correct format.
  • Monitor the queue length and adjust the MAX_QUEUE_LENGTH value accordingly to prevent requests from being rejected due to a full queue.
  • Implement retry mechanisms for handling temporary errors or failures during the video concatenation process.
  • Provide meaningful and descriptive id values to easily identify requests in the response.

8. Best Practices

  • Validate the video URLs before sending the request to ensure they are accessible and in the correct format.
  • Monitor the queue length and adjust the MAX_QUEUE_LENGTH value accordingly to prevent requests from being rejected due to a full queue.
  • Implement retry mechanisms for handling temporary errors or failures during the video concatenation process.
  • Provide meaningful and descriptive id values to easily identify requests in the response.

Kiểm tra Trạng thái Công việc

Sau khi gửi một công việc, bạn có thể kiểm tra trạng thái của nó bằng cách sử dụng job_id được trả về trong phản hồi.

Endpoint

URL Path: https://revidapi.com/v1/job/status
HTTP Method: POST

Yêu cầu

Headers

  • x-api-key (bắt buộc): API key để xác thực.
  • Content-Type: application/json

Tham số Body

{
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}

Ví dụ Yêu cầu

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"}' \
  https://revidapi.com/v1/job/status

Phản hồi

Phản hồi Thành công

{
  "endpoint": "/v1/toolkit/job/status",
  "code": 200,
  "id": null,
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  "response": {
    "job_status": "done",
    "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "queue_id": 140368864456064,
    "process_id": 123456,
    "response": {
      "endpoint": "/v1/endpoint/name",
      "code": 200,
      "id": "request-123",
      "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
      "response": "https://cloud-storage.example.com/output.mp4",
      "message": "success",
      "pid": 123456,
      "queue_id": 140368864456064,
      "run_time": 2.345,
      "queue_time": 0.123,
      "total_time": 2.468,
      "queue_length": 0,
      "build_number": "1.0.0"
    }
  },
  "message": "success",
  "pid": 123456,
  "queue_id": 140368864456064,
  "run_time": 0.001,
  "queue_time": 0.0,
  "total_time": 0.001,
  "queue_length": 0,
  "build_number": "1.0.0"
}

Phản hồi Lỗi

  • 404 Not Found: Nếu không tìm thấy công việc với job_id được cung cấp:
{
  "error": "Job not found",
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}
  • 500 Internal Server Error: Nếu xảy ra lỗi không mong muốn:
{
  "error": "Failed to retrieve job status: <error_message>",
  "code": 500
}