FFmpeg Editor API

Process and transform media using your own FFmpeg command safely on our infrastructure. Submit a job with your media and a command template, then poll the job until it finishes and download the result.

Endpoint

POST /api/uploadposts/ffmpeg/jobs/upload

Headers

Name	Value	Description
Authorization	Apikey your-api-key-here	Your API key for authentication.

Parameters

Name	Type	Required	Description
file	File (binary)	Yes	Media file to process.
full_command	String	Yes	FFmpeg command template that MUST use {input} and {output} placeholders. Example: ffmpeg -y -i {input} -c:v libx264 -crf 23 {output}
output_extension	String	Yes	Desired output file extension (e.g., mp4, wav, mp3, mov, webm).

Note: If the duration of the input media cannot be detected, the system assumes 60 seconds for quota calculation.

Command Template Rules

For security and reliability, only safe FFmpeg commands are accepted.

• Use placeholders: {input} for the input file and {output} for the output file; do not hardcode filenames.
• Allowed pattern starts with ffmpeg and may include typical flags (e.g., -y, -i, -c:v, -c:a, -r, -b:v, filters, etc.).
• Blocked characters/constructs to prevent command injection: ;, |, &, $, \``, $(, newlines, carriage returns, and destructive commands like rm/rmdir`.
• If validation fails, the API returns 400 Bad Request with a helpful message.

Responses

• 202 Accepted (job created)

{
  "success": true,
  "job_id": "a97bbb5a-139b-46ca-b893-6e8d303d5934",
  "status": "PENDING"
}

Check Job Status

Poll the job until it finishes.

GET /api/uploadposts/ffmpeg/jobs/{job_id}

Example response:

{
  "job_id": "a97bbb5a-139b-46ca-b893-6e8d303d5934",
  "status": "FINISHED",
  "duration_seconds": 120,
  "output_extension": "mp4"
}

Statuses: PENDING, PROCESSING, FINISHED, ERROR.

Download Result

When status is FINISHED, download the processed file.

GET /api/uploadposts/ffmpeg/jobs/{job_id}/download

Response headers include the appropriate Content-Type and a Content-Disposition attachment filename (e.g., output.mp4, output.wav). The response body is the binary media.

Example: Convert to MP4 (H.264)

curl \
  -H 'Authorization: Apikey your-api-key-here' \
  -F 'file=@/path/to/input.mov' \
  -F 'full_command=ffmpeg -y -i {input} -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k {output}' \
  -F 'output_extension=mp4' \
  -X POST https://api.upload-post.com/api/uploadposts/ffmpeg/jobs/upload

Example: Extract Audio to WAV

curl \
  -H 'Authorization: Apikey your-api-key-here' \
  -F 'file=@/path/to/input.mp4' \
  -F 'full_command=ffmpeg -y -i {input} -vn -acodec pcm_s16le -ar 44100 -ac 2 {output}' \
  -F 'output_extension=wav' \
  -X POST https://api.upload-post.com/api/uploadposts/ffmpeg/jobs/upload

Quotas by Plan (minutes of media/month)

Plan	Minutes/Month
free	30
basic	300
professional	1000
advanced	3000
business	10000

Resets on the 1st of each month at 00:00 UTC.

Errors

• 400 Bad Request: Invalid or unsafe FFmpeg command, missing parameters.
• 401 Unauthorized: Invalid or expired API key.
• 404 Not Found: Job not found.
• 429 Too Many Requests: Monthly quota exceeded (response includes current usage when applicable).
• 500 Internal Server Error: Processing error.

Notes

• Jobs are asynchronous; always poll the job status before attempting to download the output.
• Quota checks use detected media duration to ensure fair usage across plans.