← All guides

Use the FFmpeg API in TypeScript

Add fully typed FFmpeg video processing to any TypeScript runtime with a simple REST API.

What you can build

  • Transcode and convert video between MP4, WebM, and MOV
  • Generate thumbnails and extract still frames
  • Pull audio tracks out of video for podcasts and transcription
  • Resize, crop, watermark, and run custom FFmpeg options
  • Batch-process at scale without managing servers or a queue

Why not install FFmpeg in TypeScript?

Running FFmpeg yourself (for example, fluent-ffmpeg with hand-written types) means shipping binaries, keeping codec builds in sync across environments, and giving video encoding its own CPU and scaling story. With the API you send an HTTP request, the job runs on dedicated hardware, and you pay only for the processing time you use. Nothing to install.

Quickstart

Grab a free API key from the dashboard (free tier, no card), then submit a job. It's one HTTP call, so it works from any TypeScript HTTP client.

curl -X POST https://api.ffmpeg-micro.com/v1/transcodes \
  -H "Authorization: Bearer $FFMPEG_MICRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs":[{"url":"gs://your-bucket/input.mp4"}],"outputFormat":"mp4"}'

The API returns a job id. Poll GET /v1/transcodes/{id} until the status is completed, then fetch a signed download URL from /download. See the quickstart for the full upload, process, and download flow.

Troubleshooting

What the API returns when a request from TypeScript goes wrong, and what to change.

401 Authorization required
The request arrived with no Authorization: Bearer header. Send your API key as a bearer token on every call.
401 Invalid API key
The key is not one the API recognizes. Copy it again from the API keys page of your dashboard and check that nothing was cut off or wrapped in quotes.
400 Missing required field
A transcode needs an inputs array with at least one url, plus an outputFormat. More than 10 inputs in one job returns Too many inputs.
400 Placeholder bucket name
The request still carries an example URL such as gs://your-bucket/input.mp4. Swap in the fileUrl that POST /v1/upload/confirm returned for your own upload.
400 with details
Invalid input, Invalid GCS URL, Invalid input URL, Invalid FFmpeg options and Invalid FFmpeg input options all mean the API rejected one part of the request, and details says which part and why: an input URL, the output format, a filter or an option. For a URL, a gs:// input has to point into the upload bucket, which the fileUrl from the confirm call does, and a file hosted anywhere else goes in as a full HTTP or HTTPS URL.
402 with an upgrade_url
The account has nothing left to run a job with. The response body says so and carries the link to add tokens or change plan.
Status failed
GET /v1/transcodes/{id} returns the reason in error_message. A job that needs more than the account has left fails this way with Quota exceeded, and so does a file over your plan's size limit, with File too large, the file's size and the limit.
400 Transcode not completed
/download works only once status is completed. Poll GET /v1/transcodes/{id} until it is, and stop if it turns failed or canceled: those jobs return this error too and never complete. The signed URL lasts 10 minutes, so ask for it when you are ready to download.

TypeScript guides

In-depth, code-first walkthroughs for TypeScript.

How to Use FFmpeg with TypeScript (No Installation Required)
How to process video in TypeScript without installing FFmpeg. Compare child_process, fluent-ffmpeg, ffmpeg.wasm, and cloud API approaches with typed code.

Start processing video in TypeScript

Free tier included, no credit card, no FFmpeg install.

Start FreeAPI Docs