# FFmpeg REST API - **OpenAPI Version:** `3.1.0` - **API Version:** `1.0.0` A REST API wrapper for FFmpeg media processing operations ## Servers - **URL:** `http://localhost:3000` - **Description:** Development server ## Operations ### GET / - **Method:** `GET` - **Path:** `/` - **Tags:** General #### Responses ##### Status: 200 API documentation and readme ###### Content-Type: text/html `string` **Example:** ``` "

FFmpeg REST API

" ``` ### GET /endpoints - **Method:** `GET` - **Path:** `/endpoints` - **Tags:** General #### Responses ##### Status: 200 List of all available endpoints ###### Content-Type: application/json - **`endpoints` (required)** `array` **Items:** - **`description` (required)** `string` - **`method` (required)** `string` - **`path` (required)** `string` **Example:** ``` { "endpoints": [ { "path": "", "method": "", "description": "" } ] } ``` ##### Status: 500 Internal server error ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### GET /health - **Method:** `GET` - **Path:** `/health` - **Tags:** General #### Responses ##### Status: 200 System is active and running ###### Content-Type: application/json - **`status` (required)** `string` - **`timestamp` (required)** `string` - **`uptime` (required)** `number` - **`version` (required)** `string` **Example:** ``` { "status": "ok", "uptime": 120.5, "timestamp": "2024-01-01T12:00:00Z", "version": "1.0.0" } ``` ### POST /audio/mp3 - **Method:** `POST` - **Path:** `/audio/mp3` - **Tags:** Audio #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Audio converted to MP3 format ###### Content-Type: audio/mpeg `string`, format: `binary` — Media file to process **Example:** ``` {} ``` ##### Status: 400 Invalid audio file or unsupported format ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Conversion failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /audio/wav - **Method:** `POST` - **Path:** `/audio/wav` - **Tags:** Audio #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Audio converted to WAV format ###### Content-Type: audio/wav `string`, format: `binary` — Media file to process **Example:** ``` {} ``` ##### Status: 400 Invalid audio file or unsupported format ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Conversion failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /audio/mp3/url - **Method:** `POST` - **Path:** `/audio/mp3/url` - **Tags:** Audio #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Audio converted to MP3 and uploaded to S3 ###### Content-Type: application/json - **`url` (required)** `string`, format: `uri` **Example:** ``` { "url": "https://pub-xxx.r2.dev/ffmpeg-rest/2025-01-05-abc123/output.mp3" } ``` ##### Status: 400 Invalid audio file or S3 mode not enabled ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Conversion failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /audio/wav/url - **Method:** `POST` - **Path:** `/audio/wav/url` - **Tags:** Audio #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Audio converted to WAV and uploaded to S3 ###### Content-Type: application/json - **`url` (required)** `string`, format: `uri` **Example:** ``` { "url": "https://pub-xxx.r2.dev/ffmpeg-rest/2025-01-05-abc123/output.mp3" } ``` ##### Status: 400 Invalid audio file or S3 mode not enabled ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Conversion failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /video/mp4 - **Method:** `POST` - **Path:** `/video/mp4` - **Tags:** Video #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Video converted to MP4 format ###### Content-Type: video/mp4 `string`, format: `binary` — Media file to process **Example:** ``` {} ``` ##### Status: 400 Invalid video file or unsupported format ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Conversion failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /video/audio - **Method:** `POST` - **Path:** `/video/audio` - **Tags:** Video #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Extracted audio track as WAV file ###### Content-Type: audio/wav `string`, format: `binary` — Media file to process **Example:** ``` {} ``` ##### Status: 400 Invalid video file or no audio track found ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Extraction failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /video/frames - **Method:** `POST` - **Path:** `/video/frames` - **Tags:** Video #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Extracted frames as compressed archive ###### Content-Type: application/zip `string`, format: `binary` — Media file to process **Example:** ``` {} ``` ###### Content-Type: application/gzip `string`, format: `binary` — Media file to process **Example:** ``` {} ``` ##### Status: 400 Invalid video file or parameters ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Frame extraction failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /video/mp4/url - **Method:** `POST` - **Path:** `/video/mp4/url` - **Tags:** Video #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Video converted to MP4 and uploaded to S3 ###### Content-Type: application/json - **`url` (required)** `string`, format: `uri` **Example:** ``` { "url": "https://pub-xxx.r2.dev/ffmpeg-rest/2025-01-05-abc123/output.mp3" } ``` ##### Status: 400 Invalid video file or S3 mode not enabled ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Conversion failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /video/audio/url - **Method:** `POST` - **Path:** `/video/audio/url` - **Tags:** Video #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Extracted audio track uploaded to S3 ###### Content-Type: application/json - **`url` (required)** `string`, format: `uri` **Example:** ``` { "url": "https://pub-xxx.r2.dev/ffmpeg-rest/2025-01-05-abc123/output.mp3" } ``` ##### Status: 400 Invalid video file or S3 mode not enabled ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Extraction failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /video/frames/url - **Method:** `POST` - **Path:** `/video/frames/url` - **Tags:** Video #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Extracted frames archive uploaded to S3 ###### Content-Type: application/json - **`url` (required)** `string`, format: `uri` **Example:** ``` { "url": "https://pub-xxx.r2.dev/ffmpeg-rest/2025-01-05-abc123/output.mp3" } ``` ##### Status: 400 Invalid video file or S3 mode not enabled ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Frame extraction failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### GET /video/frames/{filename} - **Method:** `GET` - **Path:** `/video/frames/{filename}` - **Tags:** Video #### Responses ##### Status: 200 Downloaded frame image ###### Content-Type: image/png `string`, format: `binary` — Media file to process **Example:** ``` {} ``` ##### Status: 404 Frame not found ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Download failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /image/jpg - **Method:** `POST` - **Path:** `/image/jpg` - **Tags:** Image #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Image converted to JPG format ###### Content-Type: image/jpeg `string`, format: `binary` — Media file to process **Example:** ``` {} ``` ##### Status: 400 Invalid image file or unsupported format ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Conversion failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /image/jpg/url - **Method:** `POST` - **Path:** `/image/jpg/url` - **Tags:** Image #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Image converted to JPG and uploaded to S3 ###### Content-Type: application/json - **`url` (required)** `string`, format: `uri` **Example:** ``` { "url": "https://pub-xxx.r2.dev/ffmpeg-rest/2025-01-05-abc123/output.mp3" } ``` ##### Status: 400 Invalid image file or S3 mode not enabled ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Conversion failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /image/resize - **Method:** `POST` - **Path:** `/image/resize` - **Tags:** Image #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Image resized (preserves original format) ###### Content-Type: application/octet-stream `string`, format: `binary` — Media file to process **Example:** ``` {} ``` ##### Status: 400 Invalid parameters or image file ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Resize failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /image/resize/url - **Method:** `POST` - **Path:** `/image/resize/url` - **Tags:** Image #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Image resized and uploaded to S3 ###### Content-Type: application/json - **`url` (required)** `string`, format: `uri` **Example:** ``` { "url": "https://pub-xxx.r2.dev/ffmpeg-rest/2025-01-05-abc123/output.mp3" } ``` ##### Status: 400 Invalid parameters, image file, or S3 mode not enabled ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Resize failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### POST /media/info - **Method:** `POST` - **Path:** `/media/info` - **Tags:** Media #### Request Body ##### Content-Type: multipart/form-data - **`file` (required)** `string`, format: `binary` — Media file to process **Example:** ``` { "file": {} } ``` #### Responses ##### Status: 200 Media file metadata and stream information ###### Content-Type: application/json - **`format` (required)** `object` - **`bit_rate` (required)** `string` - **`duration` (required)** `string` - **`filename` (required)** `string` - **`format_long_name` (required)** `string` - **`format_name` (required)** `string` - **`nb_streams` (required)** `number` - **`size` (required)** `string` - **`streams` (required)** `array` **Items:** - **`codec_name` (required)** `string` - **`codec_type` (required)** `string` - **`index` (required)** `number` - **`channels`** `number` - **`codec_long_name`** `string` - **`height`** `number` - **`sample_rate`** `string` - **`width`** `number` **Example:** ``` { "format": { "filename": "", "nb_streams": 1, "format_name": "", "format_long_name": "", "duration": "", "size": "", "bit_rate": "" }, "streams": [ { "index": 1, "codec_name": "", "codec_type": "", "codec_long_name": "", "width": 1, "height": 1, "sample_rate": "", "channels": 1 } ] } ``` ##### Status: 400 Invalid media file ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 500 Probe failed ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ##### Status: 501 Not implemented ###### Content-Type: application/json - **`error` (required)** `string` - **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ## Schemas ### EndpointsResponse - **Type:**`object` * **`endpoints` (required)** `array` **Items:** - **`description` (required)** `string` - **`method` (required)** `string` - **`path` (required)** `string` **Example:** ``` { "endpoints": [ { "path": "", "method": "", "description": "" } ] } ``` ### Error - **Type:**`object` * **`error` (required)** `string` * **`message`** `string` **Example:** ``` { "error": "Invalid file format", "message": "The uploaded file is not a valid audio format" } ``` ### UrlResponse - **Type:**`object` * **`url` (required)** `string`, format: `uri` **Example:** ``` { "url": "https://pub-xxx.r2.dev/ffmpeg-rest/2025-01-05-abc123/output.mp3" } ``` ### ProbeResponse - **Type:**`object` * **`format` (required)** `object` - **`bit_rate` (required)** `string` - **`duration` (required)** `string` - **`filename` (required)** `string` - **`format_long_name` (required)** `string` - **`format_name` (required)** `string` - **`nb_streams` (required)** `number` - **`size` (required)** `string` * **`streams` (required)** `array` **Items:** - **`codec_name` (required)** `string` - **`codec_type` (required)** `string` - **`index` (required)** `number` - **`channels`** `number` - **`codec_long_name`** `string` - **`height`** `number` - **`sample_rate`** `string` - **`width`** `number` **Example:** ``` { "format": { "filename": "", "nb_streams": 1, "format_name": "", "format_long_name": "", "duration": "", "size": "", "bit_rate": "" }, "streams": [ { "index": 1, "codec_name": "", "codec_type": "", "codec_long_name": "", "width": 1, "height": 1, "sample_rate": "", "channels": 1 } ] } ```