API Documentation

Create a video by combining a static image with an audio file from URLs. The image will be displayed for the duration of the audio. Supports async processing for large files.

Request Format

Content-Type: application/json

Parameters

Request Example

{
  "image": "https://example.com/image.jpg",
  "audio": "https://example.com/audio.mp3",
  "async": true
}

Sync Response

{
  "success": true,
  "message": "Video created successfully",
  "download_url": "https://ffmpegapi.net/download/filename.mp4",
  "filename": "unique_filename.mp4"
}

Async Response

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.",
  "status_url": "https://ffmpegapi.net/api/job/550e8400-e29b-41d4-a716-446655440000/status"
}

Concatenate multiple videos from URLs into a single video. Videos with different aspect ratios can be handled by specifying output dimensions.

Request Format

Content-Type: application/json

Parameters

Request Example

{
  "video_urls": [
    "https://example.com/video1.mp4",
    "https://example.com/video2.mp4",
    "https://example.com/video3.mp4"
  ],
  "audio_url": "https://example.com/audio.mp3",
  "subtitle_url": "https://example.com/subtitles.ass",
  "watermark_url": "https://example.com/watermark.png",
  "dimensions": "1920x1080",
  "async": true
}

Sync Response

{
  "success": true,
  "message": "Videos merged successfully",
  "download_url": "https://ffmpegapi.net/download/merged_filename.mp4",
  "filename": "unique_merged_filename.mp4"
}

Async Response

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.",
  "status_url": "https://ffmpegapi.net/api/job/550e8400-e29b-41d4-a716-446655440000/status"
}

Create a picture-in-picture video by overlaying one video on top of another with customizable positioning and scaling.

Request Format

Content-Type: application/json

Parameters

Request Example

{
  "main_video_url": "https://example.com/main-video.mp4",
  "pip_video_url": "https://example.com/overlay-video.mp4",
  "position": "top-right",
  "scale": "iw/3:ih/3",
  "audio_option": "video2",
  "async": true
}

Response

{
  "success": true,
  "message": "Picture-in-picture video created successfully",
  "download_url": "https://ffmpegapi.net/download/pip_filename.mp4",
  "filename": "unique_pip_filename.mp4"
}

Async Response

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.",
  "status_url": "https://ffmpegapi.net/api/job/550e8400-e29b-41d4-a716-446655440000/status"
}

Endpoint: /api/add_subtitles

Burns ASS subtitle files directly into videos using FFmpeg, creating a permanent overlay of subtitles.

Parameters

Example Request

curl -X POST https://ffmpegapi.net/api/add_subtitles \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/video.mp4",
    "subtitle_url": "https://example.com/subtitles.ass"
  }'

Response

{
  "success": true,
  "message": "Subtitles added successfully!",
  "filename": "uuid_subtitled_video.mp4",
  "download_url": "https://ffmpegapi.net/api/storage/uuid_subtitled_video.mp4"
}

Split an audio file into equal parts. Perfect for creating audio segments, podcast chapters, or breaking large audio files into smaller chunks.

Request Format

Content-Type: application/json

Parameters

Request Example

curl -X POST "https://ffmpegapi.net/api/split_audio" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "audio_url": "https://example.com/audio.mp3",
    "parts": 4
  }'

Response Example

{
  "success": true,
  "message": "Audio successfully split into 4 parts",
  "parts": 4,
  "audio_parts": [
    {
      "part": "split_part_01.mp3",
      "download_url": "https://ffmpegapi.net/download/uuid/split_part_01.mp3"
    },
    {
      "part": "split_part_02.mp3", 
      "download_url": "https://ffmpegapi.net/download/uuid/split_part_02.mp3"
    },
    {
      "part": "split_part_03.mp3",
      "download_url": "https://ffmpegapi.net/download/uuid/split_part_03.mp3"
    },
    {
      "part": "split_part_04.mp3",
      "download_url": "https://ffmpegapi.net/download/uuid/split_part_04.mp3"
    }
  ]
}

Async Processing Example

curl -X POST "https://ffmpegapi.net/api/split_audio" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "audio_url": "https://example.com/long_audio.mp3",
    "parts": 8,
    "async": true
  }'

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.",
  "status_url": "https://ffmpegapi.net/api/job/550e8400-e29b-41d4-a716-446655440000/status"
}

Trim an audio file to a specific duration. Perfect for creating shorter audio clips, removing unwanted sections, or preparing audio for video overlay.

Request Parameters

Example Request

curl -X POST "https://ffmpegapi.net/api/trim_audio" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "audio_url": "https://example.com/audio.mp3",
       "desired_length": 120.5,
       "fade_duration": 10
     }'

Success Response

{
  "success": true,
  "filename": "trimmed_audio_1694022400.mp3",
  "download_url": "https://ffmpegapi.net/api/storage/trimmed_audio_1694022400.mp3",
  "trimmed_length": 120.5,
  "fade_duration": 10,
  "original_length": 240.0,
  "message": "Audio trimmed successfully with fade effect"
}

Error Response

{
  "success": false,
  "error": "Audio file duration (30.0 seconds) is shorter than desired length (120.5 seconds)"
}

Notes

• Format Support: Supports MP3, WAV, FLAC, AAC, OGG, and other common audio formats
• Duration Validation: Desired length cannot exceed the original audio duration
• Fade Effect: Optional fade-out creates smooth audio endings. Fade duration must be less than total length
• Fade Calculation: For 60s audio with 10s fade, fade starts at 50s (desired_length - fade_duration)
• Precision: Supports sub-second precision (e.g., 90.5 seconds)
• Quality: Output maintains original audio quality and format
• File Size: Audio file URLs must be publicly accessible and under 100MB

Code Examples

• cURL
• Python
• JavaScript
• PHP

curl -X POST "https://ffmpegapi.net/api/trim_audio" \
     -H "X-API-Key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "audio_url": "https://example.com/podcast_episode.mp3",
       "desired_length": 180,
       "fade_duration": 10
     }'

import requests
import json

url = "https://ffmpegapi.net/api/trim_audio"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "audio_url": "https://example.com/podcast_episode.mp3",
    "desired_length": 180,
    "fade_duration": 10
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result["success"]:
    print(f"Audio trimmed successfully!")
    print(f"Download URL: {result['download_url']}")
    print(f"Trimmed to: {result['trimmed_length']} seconds")
    if result.get('fade_duration', 0) > 0:
        print(f"Fade effect: {result['fade_duration']} seconds")
else:
    print(f"Error: {result['error']}")

const trimAudio = async () => {
  const response = await fetch('https://ffmpegapi.net/api/trim_audio', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      audio_url: 'https://example.com/podcast_episode.mp3',
      desired_length: 180,
      fade_duration: 10
    })
  });
  
  const result = await response.json();
  
  if (result.success) {
    console.log('Audio trimmed successfully!');
    console.log('Download URL:', result.download_url);
    console.log('Trimmed to:', result.trimmed_length, 'seconds');
    if (result.fade_duration > 0) {
      console.log('Fade effect:', result.fade_duration, 'seconds');
    }
  } else {
    console.error('Error:', result.error);
  }
};

trimAudio();

 'https://example.com/podcast_episode.mp3',
    'desired_length' => 180,
    'fade_duration' => 10
);

$options = array(
    'http' => array(
        'header' => "X-API-Key: YOUR_API_KEY\r\n" .
                   "Content-Type: application/json\r\n",
        'method' => 'POST',
        'content' => json_encode($data)
    )
);

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);
$result = json_decode($response, true);

if ($result['success']) {
    echo "Audio trimmed successfully!\n";
    echo "Download URL: " . $result['download_url'] . "\n";
    echo "Trimmed to: " . $result['trimmed_length'] . " seconds\n";
    if ($result['fade_duration'] > 0) {
        echo "Fade effect: " . $result['fade_duration'] . " seconds\n";
    }
} else {
    echo "Error: " . $result['error'] . "\n";
}
?>

Async Processing Response

When async processing is enabled for your account, you'll receive:

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.",
  "status_url": "https://ffmpegapi.net/api/job/550e8400-e29b-41d4-a716-446655440000/status"
}

Convert horizontal videos to vertical format optimized for mobile viewing. Automatically selects the best aspect ratio (3:4 or 9:16) based on the original video dimensions, with optional watermark placement in the top right corner.

Request Format

Content-Type: application/json

Parameters

Request Example

{
  "video_url": "https://example.com/horizontal_video.mp4",
  "watermark_url": "https://example.com/logo.png",
  "async": true
}

Sync Response

{
  "success": true,
  "message": "Video successfully converted to vertical 9:16 format",
  "download_url": "https://ffmpegapi.net/api/storage/vertical_video.mp4",
  "filename": "unique_filename_vertical.mp4"
}

Async Response

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.",
  "status_url": "https://ffmpegapi.net/api/job/550e8400-e29b-41d4-a716-446655440000/status"
}

Aspect Ratio Selection

The API automatically chooses between 3:4 and 9:16 aspect ratios based on which is closer to your original video's aspect ratio:

• 3:4 (1080x1440): Selected for wider horizontal videos
• 9:16 (1080x1920): Selected for narrower horizontal videos (closer to square)

The original video is scaled to fit within the target dimensions while maintaining its aspect ratio, with black bars added to fill any remaining space.

Watermark Details

• Position: Top right corner with 20px padding
• Size: Automatically scaled to 20% of video width
• Format: Supports PNG, JPG, and other common image formats
• Transparency: PNG transparency is preserved

Code Examples

• cURL
• Python
• JavaScript

curl -X POST "https://ffmpegapi.net/api/convert_to_vertical" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/video.mp4",
    "watermark_url": "https://example.com/logo.png"
  }'

import requests

url = "https://ffmpegapi.net/api/convert_to_vertical"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "video_url": "https://example.com/video.mp4",
    "watermark_url": "https://example.com/logo.png"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result["success"]:
    print(f"Video converted successfully!")
    print(f"Download URL: {result['download_url']}")
    print(f"Format: {result['message']}")
else:
    print(f"Error: {result['error']}")

const convertVideo = async () => {
  const response = await fetch('https://ffmpegapi.net/api/convert_to_vertical', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_url: 'https://example.com/video.mp4',
      watermark_url: 'https://example.com/logo.png'
    })
  });
  
  const result = await response.json();
  
  if (result.success) {
    console.log('Video converted successfully!');
    console.log('Download URL:', result.download_url);
    console.log('Format:', result.message);
  } else {
    console.error('Error:', result.error);
  }
};

convertVideo();

Check the status of an asynchronous job. Use this endpoint to monitor the progress of jobs submitted with async: true.

Parameters

Request Example

curl -X GET "https://ffmpegapi.net/api/job/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "X-API-Key: your_api_key_here"

Response Examples

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "merge_image_audio",
  "status": "pending",
  "created_at": "2025-08-19T22:00:00.000Z",
  "updated_at": "2025-08-19T22:00:00.000Z"
}

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "merge_image_audio",
  "status": "processing",
  "created_at": "2025-08-19T22:00:00.000Z",
  "updated_at": "2025-08-19T22:01:30.000Z"
}

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "merge_image_audio",
  "status": "completed",
  "created_at": "2025-08-19T22:00:00.000Z",
  "updated_at": "2025-08-19T22:03:45.000Z",
  "message": "Video created successfully",
  "download_url": "https://ffmpegapi.net/download/filename.mp4",
  "filename": "unique_filename.mp4"
}

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "merge_image_audio",
  "status": "failed",
  "created_at": "2025-08-19T22:00:00.000Z",
  "updated_at": "2025-08-19T22:02:15.000Z",
  "error": "Failed to download image: Invalid URL"
}