AI Processing

Skip the FFmpeg learning curve. Describe what you want in plain English, and our AI translates your instructions into the right FFmpeg or FFprobe command — then runs it for you.

🧪

AI Processing is in beta. The AI interprets your natural language instructions to generate commands, but results may not always be perfect. Always review the generated_command in responses before relying on them in production. We appreciate your feedback as we improve!

💰

No extra cost. AI endpoints are billed the same as standard endpoints — you only pay for the compute (GB-seconds) used to process your media. The AI translation itself is free.

Why AI Processing?

FFmpeg is incredibly powerful — but its syntax can be intimidating. Compare these two requests that do the same thing:

Traditional: /ffmpeg/process

{
"task": {
  "inputs": [
    { "file_path": "dir_abc/input.mov" }
  ],
  "outputs": [
    {
      "file": "output.mp4",
      "options": [
        "-vf", "scale=-2:720",
        "-c:v", "libx264",
        "-crf", "23",
        "-preset", "medium",
        "-c:a", "aac",
        "-b:a", "128k"
      ]
    }
  ]
}
}

Requires knowing FFmpeg options, codecs, filter syntax, and encoding parameters.

AI: /ai/ffmpeg/process

{
"inputs": [
  { "file_path": "dir_abc/input.mov" }
],
"instructions": "Convert to 720p MP4 with good compression"
}

Just describe what you want. The AI handles the rest.

How It Works

Describe

Write what you want in plain English: “Extract audio as MP3”, “Compress to 50% size”, or “Get the video resolution”

AI Translates

Our AI converts your instructions into the optimal FFmpeg or FFprobe command with the right options, codecs, and filters.

Get Results

Your media is processed and results are returned — along with the generated command so you can see exactly what ran.

Endpoints

AI Processing provides three endpoints:

Endpoint	Purpose
`POST /ai/ffmpeg/process`	Process media synchronously with natural language
`POST /ai/ffmpeg/process/async`	Process media asynchronously (returns job ID)
`POST /ai/ffprobe/analyze`	Analyze media metadata with natural language

AI FFmpeg Process (Sync)

POST /ai/ffmpeg/process — Transform media files by describing what you want. The request waits until processing is complete.

const response = await fetch("https://api.ffmpeg-api.com/ai/ffmpeg/process", {
  method: "POST",
  headers: {
    "Authorization": "Basic YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    inputs: [{ file_path: "dir_abc123/video.mov" }],
    instructions: "Convert to 720p MP4 with good compression"
  })
});
 
const data = await response.json();
console.log(data.result);            // Output files with download URLs
console.log(data.generated_command);  // The FFmpeg command the AI created

import requests
 
response = requests.post(
    "https://api.ffmpeg-api.com/ai/ffmpeg/process",
    headers={"Authorization": "Basic YOUR_API_KEY"},
    json={
        "inputs": [{"file_path": "dir_abc123/video.mov"}],
        "instructions": "Convert to 720p MP4 with good compression"
    }
)
 
data = response.json()
print(data["result"])             # Output files with download URLs
print(data["generated_command"])  # The FFmpeg command the AI created

curl -X POST https://api.ffmpeg-api.com/ai/ffmpeg/process \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"file_path": "dir_abc123/video.mov"}],
    "instructions": "Convert to 720p MP4 with good compression"
  }'

Request Body

Required Fields

inputs[] — Array of input files. Each must have a file_path (dir_id/filename or HTTPS URL).
instructions — Plain English description of what you want done to the media.

Optional Fields

output_dir_id — Directory for output files. Defaults to the input file’s directory, or a new temp directory for URL-only inputs.

Response

{
  "ok": true,
  "result": [
    {
      "file_name": "output.mp4",
      "size_bytes": 1234567,
      "download_url": "https://storage.example.com/result.mp4"
    }
  ],
  "usage": {
    "time_sec": 8.3,
    "input_size_gb": 0.098,
    "output_size_gb": 0.015,
    "gb_sec": 0.8134
  },
  "generated_command": {
    "inputs": [{ "file_path": "dir_abc123/video.mov" }],
    "outputs": [{ "file": "output.mp4", "options": ["-vf", "scale=-2:720", "-crf", "23", "-preset", "medium"] }]
  }
}

About generated_command: Every response includes the FFmpeg task the AI created from your instructions. This lets you verify what ran, learn FFmpeg syntax, or use the command directly with the traditional /ffmpeg/process endpoint next time.

⏱️

Long-running tasks may time out on the sync endpoint. For large files or complex operations, use the async endpoint below.

AI FFmpeg Process (Async)

POST /ai/ffmpeg/process/async — Same AI-powered processing, but returns immediately with a job ID. Ideal for large files or long-running operations.

// Submit the job
const response = await fetch("https://api.ffmpeg-api.com/ai/ffmpeg/process/async", {
  method: "POST",
  headers: {
    "Authorization": "Basic YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    inputs: [{ file_path: "dir_abc123/long-video.mp4" }],
    instructions: "Compress video to half its size while keeping good quality",
    webhook_url: "https://yoursite.com/callback"  // optional
  })
});
 
const { job_id, generated_command } = await response.json();
 
// Poll for results (or use webhook instead)
const status = await fetch(`https://api.ffmpeg-api.com/job/${job_id}`, {
  headers: { "Authorization": "Basic YOUR_API_KEY" }
}).then(r => r.json());

import requests
import time
 
# Submit the job
response = requests.post(
    "https://api.ffmpeg-api.com/ai/ffmpeg/process/async",
    headers={"Authorization": "Basic YOUR_API_KEY"},
    json={
        "inputs": [{"file_path": "dir_abc123/long-video.mp4"}],
        "instructions": "Compress video to half its size while keeping good quality",
        "webhook_url": "https://yoursite.com/callback"  # optional
    }
)
 
job_id = response.json()["job_id"]
 
# Poll for results (or use webhook instead)
while True:
    status = requests.get(
        f"https://api.ffmpeg-api.com/job/{job_id}",
        headers={"Authorization": "Basic YOUR_API_KEY"}
    ).json()
    if status["status"] in ["completed", "failed"]:
        break
    time.sleep(2)

# Submit the job
curl -X POST https://api.ffmpeg-api.com/ai/ffmpeg/process/async \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"file_path": "dir_abc123/long-video.mp4"}],
    "instructions": "Compress video to half its size while keeping good quality",
    "webhook_url": "https://yoursite.com/callback"
  }'
 
# Poll for results
curl -H "Authorization: Basic YOUR_API_KEY" \
  https://api.ffmpeg-api.com/job/JOB_ID_HERE

Request Body

Required Fields

inputs[] — Array of input files with file_path
instructions — Plain English description

Optional Fields

output_dir_id — Target directory for outputs
webhook_url — HTTPS URL to receive results when the job completes. Must be publicly accessible (no localhost or private IPs).

Response (202 Accepted)

{
  "ok": true,
  "job_id": "job_abc123xyz",
  "status": "pending",
  "generated_command": {
    "inputs": [{ "file_path": "dir_abc123/long-video.mp4" }],
    "outputs": [{ "file": "output.mp4", "options": ["-crf", "28", "-preset", "slow"] }]
  }
}

Tip: The generated_command is returned immediately in the 202 response so you can review it even before processing finishes.

AI FFprobe Analyze

POST /ai/ffprobe/analyze — Ask questions about your media files in plain English. The AI determines the right FFprobe options to get the information you need.

const response = await fetch("https://api.ffmpeg-api.com/ai/ffprobe/analyze", {
  method: "POST",
  headers: {
    "Authorization": "Basic YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    file_path: "dir_abc123/video.mp4",
    instructions: "What is the resolution, duration, and codec?"
  })
});
 
const data = await response.json();
console.log(data.result);          // FFprobe output
console.log(data.generated_probe); // The probe options the AI selected

import requests
 
response = requests.post(
    "https://api.ffmpeg-api.com/ai/ffprobe/analyze",
    headers={"Authorization": "Basic YOUR_API_KEY"},
    json={
        "file_path": "dir_abc123/video.mp4",
        "instructions": "What is the resolution, duration, and codec?"
    }
)
 
data = response.json()
print(data["result"])          # FFprobe output
print(data["generated_probe"]) # The probe options the AI selected

curl -X POST https://api.ffmpeg-api.com/ai/ffprobe/analyze \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "dir_abc123/video.mp4",
    "instructions": "What is the resolution, duration, and codec?"
  }'

Request Body

Required Fields

file_path — File to analyze: dir_id/filename or HTTPS URL
instructions — Plain English description of what metadata you want

Response

{
  "ok": true,
  "result": {
    "format": {
      "duration": "120.5",
      "size": "15728640"
    },
    "streams": [
      {
        "codec_name": "h264",
        "width": 1920,
        "height": 1080
      }
    ]
  },
  "usage": {
    "time_sec": 1.8,
    "input_size_gb": 0.015,
    "output_size_gb": 0.0001,
    "gb_sec": 0.027
  },
  "generated_probe": {
    "format": ["duration", "size"],
    "streams": ["codec_name", "width", "height"],
    "select_streams": "v:0"
  }
}

URL Support: You can analyze files directly from HTTPS URLs without uploading. Just pass the URL as file_path.

Example Instructions

Here are examples of instructions you can use. Be as specific as possible for the best results.

FFmpeg Processing

Format Conversion

”Convert this MOV file to MP4”

Resolution & Compression

”Resize to 720p and compress with high quality”

Audio Extraction

”Extract audio and save as high-quality MP3”

Thumbnail Generation

”Create a thumbnail from the 10 second mark as a 640x360 JPEG”

Trimming

”Trim the video from 30 seconds to 1 minute 15 seconds”

GIF Creation

”Create a 5-second GIF starting at the 20 second mark, 480px wide”

Audio Conversion

”Convert WAV to AAC at 192kbps”

Video for Web

”Optimize this video for web streaming with fast start”

FFprobe Analysis

”What is the video resolution and duration?"

"What codecs and bitrates are used?"

"How many audio streams does this file have?"

"Get the frame rate and pixel format of the video”

Tips for Best Results

Be specific about formats and quality

Instead of: “Make the video smaller”

Try: “Compress to MP4 at 720p with CRF 28” or “Reduce file size by about 50% while keeping decent quality”

Mention output format explicitly

Instead of: “Get the audio”

Try: “Extract audio and save as MP3” or “Extract audio as WAV at 44100Hz”

Include dimensions and timestamps when relevant

Instead of: “Make a thumbnail”

Try: “Create a JPEG thumbnail at the 5 second mark, 640x360”

Check the generated command

Every response includes the actual FFmpeg/FFprobe command that was generated. Review generated_command or generated_probe to verify the AI understood your intent correctly.

Limitations & Beta Expectations

🧪

AI Processing is a beta feature. Here’s what to expect:

AI interpretation may vary — Ambiguous instructions may produce different results. Be specific for consistent output.
Complex filter graphs — Multi-input workflows with overlays, picture-in-picture, or complex filter chains may not always generate correctly. For these, consider using the traditional Processing endpoint.
Review before production — Always check the generated_command or generated_probe field in responses before relying on AI-generated commands in production workflows.
Feedback welcome — If you encounter unexpected results, let us know. Your feedback helps us improve the AI.

AI Processing

Why AI Processing?

How It Works

Describe

AI Translates

Get Results

Endpoints

AI FFmpeg Process (Sync)

Request Body

Required Fields

Optional Fields

Response

AI FFmpeg Process (Async)

Request Body

Required Fields

Optional Fields

Response (202 Accepted)

AI FFprobe Analyze

Request Body

Required Fields

Response

Example Instructions

FFmpeg Processing

FFprobe Analysis

Tips for Best Results

Be specific about formats and quality

Mention output format explicitly

Include dimensions and timestamps when relevant

Check the generated command

Limitations & Beta Expectations

What’s Next?

Processing

Examples

API Reference