Media Convert Endpoint Documentation

1. Overview

The https://api.revidapi.com/paid/media/convert endpoint is part of the Flask API application and is responsible for converting media files (audio or video) from one format to another.

RevidAPI Tutorials

2. Endpoint

URL Path: https://api.revidapi.com/paid/media/convert 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:

• media_url (required, string): The URL of the media file to be converted.
• format (required, string): The desired output format for the converted media file.
• video_codec (optional, string): The video codec to be used for the conversion. Default is libx264.
• video_preset (optional, string): The video preset to be used for the conversion. 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 be used for the conversion. Default is aac.
• audio_bitrate (optional, string): The audio bitrate to be used for the conversion. Default is 128k.
• webhook_url (optional, string): The URL to receive a webhook notification upon completion of the conversion process.
• id (optional, string): An optional identifier for the conversion request.

Example Request

{
  "media_url": "https://example.com/video.mp4",
  "format": "avi",
  "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/media/convert \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "media_url": "https://example.com/video.mp4",
    "format": "avi",
    "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 will be a JSON object containing the URL of the converted media file uploaded to cloud storage, the endpoint path, and a status code of 200.

{
  "code": 200,
  "id": "unique-request-id",
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  "response": "https://cloud.example.com/converted-video.avi",
  "message": "success",
  "pid": 12345,
  "queue_id": 1234567890,
  "run_time": 10.234,
  "queue_time": 0.123,
  "total_time": 10.357,
  "queue_length": 0,
  "build_number": "1.0.0"
}

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.
• 500 Internal Server Error: Returned when an unexpected error occurs during the conversion process.

Example error response:

{
  "code": 400,
  "id": "unique-request-id",
  "job_id": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  "message": "Invalid request payload",
  "pid": 12345,
  "queue_id": 1234567890,
  "queue_length": 0,
  "build_number": "1.0.0"
}

5. Error Handling

The endpoint uses the validate_payload decorator to validate the request payload against a JSON schema. If the payload is missing or invalid, a 400 Bad Request error is returned.

The authenticate decorator is used to ensure that the request includes a valid x-api-key header. If the header is missing or invalid, a 401 Unauthorized error is returned.

If an unexpected error occurs during the conversion process, a 500 Internal Server Error is returned, and the error is logged.

6. Usage Notes

• The media_url parameter must be a valid URL pointing to the media file to be converted.
• The format parameter must be a valid media format supported by the conversion process.
• The optional parameters (video_codec, video_preset, video_crf, audio_codec, audio_bitrate) allow you to customize the conversion settings.
• If the webhook_url parameter is provided, a webhook notification will be sent to the specified URL upon completion of the conversion process.
• The id parameter is optional and can be used to identify the conversion request.

7. Common Issues

• Providing an invalid or inaccessible media_url.
• Specifying an unsupported format.
• Providing invalid values for the optional parameters (e.g., video_crf outside the valid range).

8. Best Practices

• Always validate the input parameters on the client-side before sending the request.
• Use the id parameter to track and identify conversion requests.
• Provide a webhook_url to receive notifications about the conversion process completion.
• Monitor the API logs for any errors or issues during the conversion process.
• Consider implementing rate limiting or queue management to handle high volumes of requests.