Video Editting API Endpoint¶

Pricing¶

35 credits per request

Fixed cost regardless of video length or file size.

Overview¶

The https://revidapi.com/v1/video/edit endpoint is a flexible and powerful API that allows users to video edit commands by providing input files, filters, and output options.

Video Editting Tutorials

2. Endpoint¶

URL Path: https://revidapi.com/v1/video/edit HTTP Method: POST

3. Request¶

Headers¶

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

Body Parameters¶

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

inputs (required, array): An array of input file objects, each containing:
file_url (required, string): The URL of the input file.
Additional parameters vary based on the editing operation. Please refer to the Video Editting Tutorials for detailed documentation.

Example Request¶

Take video1.mp4 → cut from 10 seconds, duration 20 seconds.
Take video2.mp4 → use the full video.

{
  "inputs": [
    {
      "file_url": "https://example.com/video1.mp4",
      "options": [
        {
          "option": "-ss",
          "argument": 10
        },
        {
          "option": "-t",
          "argument": 20
        }
      ]
    },
    {
      "file_url": "https://example.com/video2.mp4"
    }
  ],
  "filters": [
    {
      "filter": "hflip"
    }
  ],
  "outputs": [
    {
      "options": [
        {
          "option": "-c:v",
          "argument": "libx264"
        },
        {
          "option": "-crf",
          "argument": 23
        }
      ]
    }
  ],
  "global_options": [
    {
      "option": "-y"
    }
  ],
  "metadata": {
    "thumbnail": true,
    "filesize": true,
    "duration": true,
    "bitrate": true,
    "encoder": true
  },
  "webhook_url": "https://example.com/webhook",
  "id": "unique-request-id"
}

curl -X POST \
  https://revidapi.com/v1/video/edit \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": [
      {
        "file_url": "https://example.com/video1.mp4",
        "options": [
          {
            "option": "-ss",
            "argument": 10
          },
          {
            "option": "-t",
            "argument": 20
          }
        ]
      },
      {
        "file_url": "https://example.com/video2.mp4"
      }
    ],
    "filters": [
      {
        "filter": "hflip"
      }
    ],
    "outputs": [
      {
        "options": [
          {
            "option": "-c:v",
            "argument": "libx264"
          },
          {
            "option": "-crf",
            "argument": 23
          }
        ]
      }
    ],
    "global_options": [
      {
        "option": "-y"
      }
    ],
    "metadata": {
      "thumbnail": true,
      "filesize": true,
      "duration": true,
      "bitrate": true,
      "encoder": true
    },
    "webhook_url": "https://example.com/webhook",
    "id": "unique-request-id"
  }'

Example Add Logo/Image to video¶

{
  "inputs": [
    {
      "file_url": "https://revidapi.com/video1.mp4"
    },
    {
      "file_url": "https://revidapi.com/logo.png"
    }
  ],
  "filters": [
    {
      "filter": "[1:v]scale=300:100[logo];[0:v][logo]overlay=x=main_w-overlay_w-50:y=50"
    }
  ],
  "outputs": [
    {
      "options": [
        {
          "option": "-f",
          "argument": "mp4"
        },
        {
          "option": "-c:v",
          "argument": "libx264"
        }
      ]
    }
  ],
  "metadata": {
    "thumbnail": true,
    "filesize": true,
    "duration": true,
    "bitrate": true
  },
  "id": "overlay_logo"
}

curl -X POST \
  https://revidapi.com/v1/video/edit \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": [
      {
        "file_url": "https://revidapi.com/video1.mp4"
      },
      {
        "file_url": "https://revidapi.com/logo.png"
      }
    ],
    "filters": [
      {
        "filter": "[1:v]scale=300:100[logo];[0:v][logo]overlay=x=main_w-overlay_w-50:y=50"
      }
    ],
    "outputs": [
      {
        "options": [
          {
            "option": "-f",
            "argument": "mp4"
          },
          {
            "option": "-c:v",
            "argument": "libx264"
          }
        ]
      }
    ],
    "metadata": {
      "thumbnail": true,
      "filesize": true,
      "duration": true,
      "bitrate": true
    },
    "id": "overlay_logo"
  }'

4. Response¶

Success Response¶

The response will be sent to the specified webhook_url as a JSON object with the following properties:

endpoint (string): The endpoint URL (https://revidapi.com/v1/video/edit).
code (number): The HTTP status code (200 for success).
id (string): The unique identifier for the request.
job_id (string): The unique job ID assigned to the request.
response (array): An array of output file objects, each containing:
file_url (string): The URL of the uploaded output file.
thumbnail_url (string, optional): The URL of the uploaded thumbnail, if requested.
filesize (number, optional): The file size of the output file, if requested.
duration (number, optional): The duration of the output file, if requested.
bitrate (number, optional): The bitrate of the output file, if requested.
encoder (string, optional): The encoder used for the output file, if requested.
message (string): The success message ("success").
pid (number): The process ID of the worker that processed the request.
queue_id (number): The ID of the queue used for processing the request.
run_time (number): The time taken to process the request (in seconds).
queue_time (number): The time the request spent in the queue (in seconds).
total_time (number): The total time taken to process the request, including queue time (in seconds).
queue_length (number): The current length of the processing queue.
build_number (string): The build number of the application.

Error Responses¶

400 Bad Request: The request payload is invalid or missing required parameters.
401 Unauthorized: The provided API key is invalid or missing.
429 Too Many Requests: The maximum queue length has been reached.
500 Internal Server Error: An unexpected error occurred while processing the request.

Example error response:

{
  "code": 400,
  "id": "unique-request-id",
  "job_id": "job-id",
  "message": "Invalid request payload: 'inputs' is a required property",
  "pid": 123,
  "queue_id": 456,
  "queue_length": 0,
  "build_number": "1.0.0"
}

5. Error Handling¶

The API handles various types of errors, including:

Missing or invalid parameters: If the request payload is missing required parameters or contains invalid data types, a 400 Bad Request error will be returned.
Authentication failure: If the provided API key is invalid or missing, a 401 Unauthorized error will be returned.
Queue limit reached: If the maximum queue length is reached, a 429 Too Many Requests error will be returned.
Unexpected errors: If an unexpected error occurs during request processing, a 500 Internal Server Error will be returned.

6. Usage Notes¶

The inputs array must contain at least one input file object.
The outputs array must contain at least one output option object.
The filters array is optional and can be used to apply video edit filters to the input files.
The global_options array is optional and can be used to specify global video edit options.
The metadata object is optional and can be used to request specific metadata for the output files.
The webhook_url parameter is required and specifies the URL where the response should be sent.
The id parameter is required and should be a unique identifier for the request.

7. Common Issues¶

Providing invalid or malformed input file URLs.
Specifying invalid or unsupported video edit options or filters.
Reaching the maximum queue length, resulting in a 429 Too Many Requests error.
Network or connectivity issues that prevent the response webhook from being delivered.

8. Best Practices¶

Validate input file URLs and ensure they are accessible before sending the request.
Test your video edit command locally before using the API to ensure it works as expected.
Monitor the queue length and adjust the maximum queue length as needed to prevent overloading the system.
Implement retry mechanisms for handling failed webhook deliveries or other transient errors.
Use unique and descriptive id values for each request to aid in troubleshooting and monitoring.

Get Job Status¶

After submitting a job, you can check its status using the job_id returned in the response.

Endpoint¶

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

Request¶

Headers¶

x-api-key (required): API key for authentication.
Content-Type: application/json

Body Parameters¶

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

Example Request¶

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

Response¶

Success Response¶

{
  "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"
}

Error Response¶

404 Not Found: If the job with the provided job_id is not found:

{
  "error": "Job not found",
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}

500 Internal Server Error: If an unexpected error occurs:

{
  "error": "Failed to retrieve job status: <error_message>",
  "code": 500
}