{ "openapi": "3.1.0", "info": { "title": "FFMPEG API", "version": "1.0.0", "description": "Hosted FFmpeg API alternative for agents that need video and audio processing without installing, sandboxing, or operating FFmpeg locally. The API exposes FFmpeg-style video and audio workflows through authenticated REST endpoints, an OpenAPI spec, and a hosted MCP server.", "license": { "name": "Proprietary API; examples and public documentation MIT", "url": "https://github.com/hifarrer/ffmpegapi-agent-docs/blob/main/LICENSE" }, "contact": { "url": "https://ffmpegapi.site/contact" }, "termsOfService": "https://ffmpegapi.site/terms" }, "servers": [ { "url": "https://ffmpegapi.site" } ], "paths": { "/api/merge_image_audio": { "post": { "operationId": "mergeImageAudio", "tags": [ "Image" ], "summary": "Create an MP4 video from image/audio pairs.", "description": "Combines one or more image/audio pairs. Each image is shown for the duration of its matching audio file, then the next image is displayed when the next audio begins. JSON requests should use image_urls and audio_urls arrays for multi-pair videos, or legacy image and audio strings for a single pair. Optional image transitions and a default slow zoom effect are supported.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Image and Audio Merge completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "request is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "required": [ "image_urls", "audio_urls" ] }, { "required": [ "image", "audio" ] } ], "properties": { "image_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "description": "Image URLs for multi-pair requests. Must align by index with audio_urls." }, "audio_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "description": "Audio URLs for multi-pair requests. Must align by index with image_urls." }, "image": { "type": "string", "format": "uri", "description": "Legacy single image URL." }, "audio": { "type": "string", "format": "uri", "description": "Legacy single audio URL." }, "transition_effect": { "type": "string", "enum": [ "none", "fade", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright", "slideup", "slidedown", "circlecrop", "rectcrop", "distance", "fadeblack", "fadewhite", "radial", "smoothleft", "smoothright", "smoothup", "smoothdown" ], "description": "Optional transition between image changes." }, "transition_duration": { "type": "number", "minimum": 0.1, "maximum": 5, "description": "Transition duration in seconds. Defaults to 0.5 when transition_effect is set." }, "dimensions": { "type": "string", "pattern": "^\\d+x\\d+$", "description": "Optional output dimensions such as 1280x720 or 1080x1920." }, "zoom_effect": { "type": "boolean", "default": true, "description": "Slowly zoom each image while its paired audio plays." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Image and Audio Merge request", "value": { "image_urls": [ "https://example.com/intro.jpg", "https://example.com/chapter-1.jpg" ], "audio_urls": [ "https://example.com/intro.mp3", "https://example.com/chapter-1.mp3" ], "transition_effect": "fade", "transition_duration": 0.75, "dimensions": "1280x720", "zoom_effect": true, "async": false } } } } } } } }, "/api/merge_videos": { "post": { "operationId": "mergeVideos", "tags": [ "Video" ], "summary": "Concatenate videos into a single MP4.", "description": "Downloads one or more videos, normalizes them when needed, and concatenates them. Optional audio replacement, output dimensions, subtitle burn-in, and watermark overlay are supported.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Video Merge completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_urls is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_urls" ], "properties": { "video_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "description": "Video URLs to merge. Use at least one URL." }, "audio_url": { "type": "string", "format": "uri", "description": "Optional replacement audio URL." }, "dimensions": { "type": "string", "pattern": "^\\d+x\\d+$", "examples": [ "1920x1080", "1080x1920" ], "description": "Optional output dimensions such as 1920x1080." }, "subtitle_url": { "type": "string", "format": "uri", "description": "Optional ASS/SSA subtitle URL to burn into the merged video." }, "watermark_url": { "type": "string", "format": "uri", "description": "Optional watermark image URL." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Video Merge request", "value": { "video_urls": [ "https://example.com/intro.mp4", "https://example.com/main.mp4" ], "dimensions": "1920x1080" } } } } } } } }, "/api/neonvideo_merge_videos": { "post": { "operationId": "neonvideoMergeVideos", "tags": [ "Neonvideo" ], "summary": "Concatenate videos with optional outro video support.", "description": "Downloads one or more videos, normalizes and concatenates them, and can append an outro video that keeps its own audio. Optional audio replacement, output dimensions, subtitle burn-in, and watermark overlay are supported.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Neonvideo Merge Videos completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_urls is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_urls" ], "properties": { "video_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "minItems": 1, "description": "Video URLs to merge. Use at least one URL." }, "audio_url": { "type": "string", "format": "uri", "description": "Optional replacement audio URL for the main merged video. Not used during outro playback." }, "outro_url": { "type": "string", "format": "uri", "description": "Optional outro video URL to append. The outro keeps its own audio." }, "dimensions": { "type": "string", "pattern": "^\\d+x\\d+$", "examples": [ "1920x1080", "1080x1920" ], "description": "Optional output dimensions such as 1920x1080." }, "subtitle_url": { "type": "string", "format": "uri", "description": "Optional ASS/SSA subtitle URL to burn into the merged video." }, "watermark_url": { "type": "string", "format": "uri", "description": "Optional watermark image URL." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Neonvideo Merge Videos request", "value": { "video_urls": [ "https://example.com/intro.mp4", "https://example.com/main.mp4" ], "outro_url": "https://example.com/outro.mp4", "dimensions": "1920x1080" } } } } } } } }, "/api/video_loop": { "post": { "operationId": "videoLoop", "tags": [ "Video" ], "summary": "Loop a video by count or until it matches an audio track.", "description": "Repeats one video a fixed number of times, or calculates the loop count needed to match a provided audio track. Optional watermark overlay is supported.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Video Loop completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL to loop." }, "number_of_loops": { "type": "integer", "minimum": 1, "description": "Positive number of times to repeat the video." }, "audio_url": { "type": "string", "format": "uri", "description": "Optional audio URL. Required if number_of_loops is omitted." }, "watermark_url": { "type": "string", "format": "uri", "description": "Optional watermark image URL." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Video Loop request", "value": { "video_url": "https://example.com/clip.mp4", "number_of_loops": 3 } } } } } } } }, "/api/endless_loop": { "post": { "operationId": "endlessLoop", "tags": [ "Endless" ], "summary": "Loop a video to an exact target duration.", "description": "Repeats one video until the requested duration in seconds is reached. The final loop is trimmed when the target duration is not an exact multiple of the source video length. Optional watermark overlay is supported.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndlessLoopResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Endless Loop completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4", "loops_required": 11, "video_duration_seconds": 120, "target_duration_seconds": 1205, "estimated_full_loops": 10, "partial_final_loop_seconds": 5 } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url", "duration" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL to loop." }, "duration": { "type": "number", "exclusiveMinimum": 0, "description": "Target output duration in seconds. Must be a positive number; fractional seconds are supported." }, "watermark_url": { "type": "string", "format": "uri", "description": "Optional watermark image URL." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Endless Loop request", "value": { "video_url": "https://example.com/clip.mp4", "duration": 1205 } } } } } } } }, "/api/picture_in_picture": { "post": { "operationId": "pictureInPicture", "tags": [ "Picture" ], "summary": "Overlay one video on another.", "description": "Creates a picture-in-picture composition using a main video and an overlay video with configurable position, scale, and audio source.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Picture in Picture completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "main_video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "main_video_url", "pip_video_url" ], "properties": { "main_video_url": { "type": "string", "format": "uri", "description": "Main/background video URL." }, "pip_video_url": { "type": "string", "format": "uri", "description": "Overlay/PiP video URL." }, "position": { "type": "string", "enum": [ "top-left", "top-right", "bottom-left", "bottom-right", "center" ], "default": "bottom-right", "description": "Overlay position. Common values: top-left, top-right, bottom-left, bottom-right, center." }, "scale": { "type": "string", "default": "iw/4:ih/4", "description": "FFmpeg scale expression for the overlay." }, "audio_option": { "type": "string", "enum": [ "video1", "video2", "mute" ], "default": "video1", "description": "Audio source: video1, video2, or mute." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Picture in Picture request", "value": { "main_video_url": "https://example.com/main.mp4", "pip_video_url": "https://example.com/overlay.mp4", "position": "top-right" } } } } } } } }, "/api/add_watermark": { "post": { "operationId": "addWatermark", "tags": [ "Add" ], "summary": "Overlay a watermark image onto a video.", "description": "Adds a watermark image to a video with configurable placement and scale.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Add Watermark completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url", "watermark_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." }, "watermark_url": { "type": "string", "format": "uri", "description": "Watermark image URL." }, "position": { "type": "string", "enum": [ "top-left", "top-center", "top-right", "middle-left", "middle", "middle-right", "bottom-left", "bottom-center", "bottom-right" ], "default": "bottom-right", "description": "One of top-left, top-center, top-right, middle-left, middle, middle-right, bottom-left, bottom-center, bottom-right." }, "scale": { "type": "number", "minimum": 0.05, "maximum": 1, "default": 0.25, "description": "Watermark width as a fraction of video width, from 0.05 to 1.0." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Add Watermark request", "value": { "video_url": "https://example.com/video.mp4", "watermark_url": "https://example.com/logo.png", "position": "bottom-right", "scale": 0.2 } } } } } } } }, "/api/add_subtitles": { "post": { "operationId": "addSubtitles", "tags": [ "Add" ], "summary": "Burn ASS subtitles into a video.", "description": "Downloads a video and an ASS/SSA subtitle file, then burns the subtitles into the output video.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Add Subtitles completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url", "subtitle_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." }, "subtitle_url": { "type": "string", "format": "uri", "description": "ASS/SSA subtitle file URL." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Add Subtitles request", "value": { "video_url": "https://example.com/video.mp4", "subtitle_url": "https://example.com/subtitles.ass" } } } } } } } }, "/api/split_audio": { "post": { "operationId": "splitAudio", "tags": [ "Split" ], "summary": "Split audio into equal parts.", "description": "Splits an audio file into a requested number of equal-duration parts.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SplitAudioPartsResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Audio split into 3 parts successfully", "parts": 3, "audio_parts": [ { "part": "part_001.mp3", "download_url": "https://ffmpegapi.site/download/job_abc123/part_001.mp3" }, { "part": "part_002.mp3", "download_url": "https://ffmpegapi.site/download/job_abc123/part_002.mp3" }, { "part": "part_003.mp3", "download_url": "https://ffmpegapi.site/download/job_abc123/part_003.mp3" } ] } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "audio_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "audio_url" ], "properties": { "audio_url": { "type": "string", "format": "uri", "description": "Audio URL." }, "parts": { "type": "integer", "minimum": 2, "maximum": 20, "default": 2, "description": "Number of equal parts, from 2 to 20." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Split Audio request", "value": { "audio_url": "https://example.com/podcast.mp3", "parts": 3 } } } } } } } }, "/api/split_audio_segments": { "post": { "operationId": "splitAudioSegments", "tags": [ "Split" ], "summary": "Split audio into fixed-duration segments.", "description": "Creates audio segments of a specified length in seconds.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SplitAudioSegmentsResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Audio split into fixed-duration segments successfully", "segment_duration": 10, "total_segments": 4, "segments": [ { "segment": "segment_001.mp3", "download_url": "https://ffmpegapi.site/download/job_abc123/segment_001.mp3" }, { "segment": "segment_002.mp3", "download_url": "https://ffmpegapi.site/download/job_abc123/segment_002.mp3" } ] } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "audio_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "audio_url" ], "properties": { "audio_url": { "type": "string", "format": "uri", "description": "Audio URL." }, "segment_duration": { "type": "number", "minimum": 1, "maximum": 3600, "default": 30, "description": "Segment duration in seconds, from 1 to 3600." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Split Audio by Segments request", "value": { "audio_url": "https://example.com/podcast.mp3", "segment_duration": 10 } } } } } } } }, "/api/split_audio_time": { "post": { "operationId": "splitAudioTime", "tags": [ "Split" ], "summary": "Extract one audio range by millisecond timestamps.", "description": "Returns the audio between start_time and end_time, both in milliseconds.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Split Audio by Time completed successfully", "download_url": "https://ffmpegapi.site/api/storage/audio_abc123.mp3", "filename": "audio_abc123.mp3" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "audio_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "audio_url", "start_time", "end_time" ], "properties": { "audio_url": { "type": "string", "format": "uri", "description": "Audio URL." }, "start_time": { "type": "number", "minimum": 0, "description": "Start time in milliseconds." }, "end_time": { "type": "number", "minimum": 0, "description": "End time in milliseconds. Must be greater than start_time." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Split Audio by Time request", "value": { "audio_url": "https://example.com/audio.mp3", "start_time": 1000, "end_time": 11000 } } } } } } } }, "/api/trim_audio": { "post": { "operationId": "trimAudio", "tags": [ "Trim" ], "summary": "Trim audio to a desired length.", "description": "Downloads an audio file and trims it to the requested duration, with optional fade-out.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrimAudioResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Trim Audio completed successfully", "download_url": "https://ffmpegapi.site/api/storage/audio_abc123.mp3", "filename": "audio_abc123.mp3", "trimmed_length": 30 } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "audio_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "audio_url", "desired_length" ], "properties": { "audio_url": { "type": "string", "format": "uri", "description": "Audio URL." }, "desired_length": { "type": "number", "minimum": 0, "description": "Output length in seconds." }, "fade_duration": { "type": "number", "minimum": 0, "default": 0, "description": "Optional fade-out duration in seconds." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Trim Audio request", "value": { "audio_url": "https://example.com/song.mp3", "desired_length": 30, "fade_duration": 2 } } } } } } } }, "/api/trim_video": { "post": { "operationId": "trimVideo", "tags": [ "Trim" ], "summary": "Trim video by start and end timestamps.", "description": "Downloads a video and returns the segment between start_time and end_time in seconds.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Trim Video completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url", "start_time", "end_time" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." }, "start_time": { "type": "number", "minimum": 0, "description": "Start time in seconds." }, "end_time": { "type": "number", "minimum": 0, "description": "End time in seconds. Must be greater than start_time." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Trim Video request", "value": { "video_url": "https://example.com/video.mp4", "start_time": 5, "end_time": 20 } } } } } } } }, "/api/split_video": { "post": { "operationId": "splitVideo", "tags": [ "Split" ], "summary": "Split a video into two parts.", "description": "Splits a video at split_at_seconds. If omitted, the split point defaults to half of the video duration.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SplitVideoResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Video split successfully", "parts": [ { "part": 1, "download_url": "https://ffmpegapi.site/api/storage/video_abc123_part1.mp4", "filename": "video_abc123_part1.mp4" }, { "part": 2, "download_url": "https://ffmpegapi.site/api/storage/video_abc123_part2.mp4", "filename": "video_abc123_part2.mp4" } ] } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." }, "split_at_seconds": { "type": "number", "minimum": 0, "description": "Split point in seconds." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Split Video request", "value": { "video_url": "https://example.com/video.mp4", "split_at_seconds": 12.5 } } } } } } } }, "/api/get_first_frame_image": { "post": { "operationId": "getFirstFrameImage", "tags": [ "Get" ], "summary": "Extract the first frame of a video as a JPEG.", "description": "Downloads a video and returns an image URL for the first frame.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameImageResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Frame extracted successfully", "image_url": "https://ffmpegapi.site/api/storage/frame_abc123.jpg", "download_url": "https://ffmpegapi.site/api/storage/frame_abc123.jpg", "filename": "frame_abc123.jpg" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Get First Frame Image request", "value": { "video_url": "https://example.com/video.mp4" } } } } } } } }, "/api/get_last_frame_image": { "post": { "operationId": "getLastFrameImage", "tags": [ "Get" ], "summary": "Extract the last frame of a video as a JPEG.", "description": "Downloads a video and returns an image URL for the last frame.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrameImageResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Frame extracted successfully", "image_url": "https://ffmpegapi.site/api/storage/frame_abc123.jpg", "download_url": "https://ffmpegapi.site/api/storage/frame_abc123.jpg", "filename": "frame_abc123.jpg" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Get Last Frame Image request", "value": { "video_url": "https://example.com/video.mp4" } } } } } } } }, "/api/convert_to_vertical": { "post": { "operationId": "convertToVertical", "tags": [ "Convert" ], "summary": "Convert a horizontal video to vertical format.", "description": "Creates a mobile-oriented vertical output and can apply an optional watermark.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Convert to Vertical completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." }, "watermark_url": { "type": "string", "format": "uri", "description": "Optional watermark image URL." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Convert to Vertical request", "value": { "video_url": "https://example.com/landscape.mp4", "watermark_url": "https://example.com/logo.png" } } } } } } } }, "/api/convert_to_tiktok_portrait": { "post": { "operationId": "convertToTiktokPortrait", "tags": [ "TikTok" ], "summary": "Convert a video to full-bleed 9:16 TikTok-style portrait.", "description": "Crops and scales source video into 1080x1920 portrait format, with optional watermark and outro video.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "TikTok Portrait Converter completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." }, "watermark_url": { "type": "string", "format": "uri", "description": "Optional watermark image URL." }, "outro_video_url": { "type": "string", "format": "uri", "description": "Optional outro video URL to append." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background." } }, "additionalProperties": false }, "examples": { "default": { "summary": "TikTok Portrait Converter request", "value": { "video_url": "https://example.com/landscape.mp4", "outro_video_url": "https://example.com/outro.mp4" } } } } } } } }, "/api/extract_audio_mp3": { "post": { "operationId": "extractAudioMp3", "tags": [ "Extract" ], "summary": "Extract a video's audio track as MP3.", "description": "Downloads a video and returns an MP3 audio file.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Extract Audio as MP3 completed successfully", "download_url": "https://ffmpegapi.site/api/storage/audio_abc123.mp3", "filename": "audio_abc123.mp3" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." }, "bitrate": { "type": "string", "enum": [ "96k", "128k", "192k", "256k", "320k" ], "default": "192k", "description": "MP3 bitrate: 96k, 128k, 192k, 256k, or 320k." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Extract Audio as MP3 request", "value": { "video_url": "https://example.com/video.mp4", "bitrate": "192k" } } } } } } } }, "/api/convert_video_to_gif": { "post": { "operationId": "convertVideoToGif", "tags": [ "Convert" ], "summary": "Encode a video as an animated GIF.", "description": "Downloads a video and creates a GIF. Optional chroma key transparency supports solid-color backgrounds such as green screen.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Convert Video to GIF completed successfully", "download_url": "https://ffmpegapi.site/api/storage/clip_abc123.gif", "filename": "clip_abc123.gif" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." }, "transparent_background": { "type": "boolean", "default": false, "description": "Apply chroma key transparency." }, "chromakey_color": { "type": "string", "default": "0x00FF00", "description": "Color to key out, such as 0x00FF00 or #00FF00." }, "similarity": { "type": "number", "minimum": 0.01, "maximum": 1, "default": 0.2, "description": "Chroma key similarity from 0.01 to 1.0." }, "blend": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.05, "description": "Transparency edge softness from 0.0 to 1.0." }, "fps": { "type": "integer", "minimum": 1, "maximum": 30, "default": 10, "description": "Output frame rate from 1 to 30." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Convert Video to GIF request", "value": { "video_url": "https://example.com/clip.mp4", "transparent_background": true, "chromakey_color": "0x00FF00", "fps": 10 } } } } } } } }, "/api/compress_video": { "post": { "operationId": "compressVideo", "tags": [ "Compress" ], "summary": "Compress a video to a smaller H.264/AAC MP4.", "description": "Downloads a video and compresses it to MP4 using quality-first CRF settings by default. Optional max dimensions avoid upscaling and optional target_size_mb uses best-effort bitrate compression for upload limits. Use async=true for large videos; hosted defaults reject inputs over 500 MB and automatically queue known inputs over 100 MB for background processing.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompressVideoResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "Video compressed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4", "original_size_bytes": 52428800, "compressed_size_bytes": 18874368, "compression_ratio": 0.36, "compression_mode": "crf" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "202": { "description": "Async job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" }, "examples": { "asyncAccepted": { "summary": "Async job accepted", "value": { "success": true, "job_id": "job_abc123", "status": "pending", "message": "Job submitted for async processing. Use /api/job/{job_id}/status to check progress.", "status_url": "https://ffmpegapi.site/api/job/job_abc123/status" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL to compress. Hosted default maximum input size is 500 MB." }, "crf": { "type": "integer", "minimum": 18, "maximum": 35, "default": 28, "description": "Quality value. Lower means higher quality and larger files." }, "preset": { "type": "string", "enum": [ "ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower" ], "default": "medium", "description": "H.264 encoding preset." }, "max_width": { "type": "integer", "minimum": 144, "maximum": 3840, "description": "Optional maximum output width. The video is not upscaled." }, "max_height": { "type": "integer", "minimum": 144, "maximum": 2160, "description": "Optional maximum output height. The video is not upscaled." }, "audio_bitrate": { "type": "string", "enum": [ "64k", "96k", "128k", "192k", "256k", "320k" ], "default": "128k", "description": "AAC audio bitrate." }, "target_size_mb": { "type": "number", "minimum": 1, "description": "Optional target output size in MiB." }, "async": { "type": "boolean", "description": "Return a job_id immediately and process in the background. Recommended for compression jobs and large videos." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Compress Video request", "value": { "video_url": "https://example.com/video.mp4", "crf": 28, "preset": "medium", "max_width": 1280, "audio_bitrate": "128k", "async": true } } } } } } } }, "/api/videos/add-tiktok-captions": { "post": { "operationId": "addTiktokCaptions", "tags": [ "AI" ], "summary": "Transcribe a video and render TikTok-style captions.", "description": "Extracts audio, transcribes it with word timestamps, and renders styled captions into a video. Also returns caption artifact URLs when available.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptionArtifactsResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "download_url": "https://ffmpegapi.site/api/storage/auto-captions/video_abc123.mp4", "captions_json_url": "https://ffmpegapi.site/api/storage/auto-captions/captions_abc123.json", "srt_url": "https://ffmpegapi.site/api/storage/auto-captions/captions_abc123.srt", "vtt_url": "https://ffmpegapi.site/api/storage/auto-captions/captions_abc123.vtt", "word_count": 142, "message": "Video with auto-generated TikTok captions rendered successfully" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "504": { "description": "Rendering timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 504 error", "value": { "success": false, "error": "Video rendering timed out. The video may be too long." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." }, "subtitle_style": { "type": "string", "enum": [ "plain-white", "yellow-bg", "pink-bg", "blue-bg", "red-bg" ], "default": "plain-white", "description": "plain-white, yellow-bg, pink-bg, blue-bg, or red-bg." }, "language": { "type": "string", "default": "auto", "description": "Language code or auto." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "4:3", "3:4" ], "default": "9:16", "description": "16:9, 9:16, 4:3, or 3:4." }, "max_chars_per_line": { "type": "integer", "minimum": 5, "maximum": 80, "default": 20, "description": "Caption wrapping limit from 5 to 80." }, "max_lines": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1, "description": "Maximum caption lines from 1 to 4." }, "position": { "type": "string", "enum": [ "top", "center", "bottom" ], "default": "bottom", "description": "top, center, or bottom." } }, "additionalProperties": false }, "examples": { "default": { "summary": "AI Captions request", "value": { "video_url": "https://example.com/video.mp4", "subtitle_style": "yellow-bg", "position": "bottom" } } } } } } } }, "/api/videos/add-text-overlay-captions": { "post": { "operationId": "addTextOverlayCaptions", "tags": [ "Text" ], "summary": "Render supplied text lines as timed caption overlays.", "description": "Displays user-provided text lines over a video, one line every duration_per_line seconds.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextOverlayCaptionResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "download_url": "https://ffmpegapi.site/api/storage/text-overlay/video_abc123.mp4", "line_count": 2, "duration_per_line": 4, "total_duration_seconds": 8, "message": "Video with text overlay captions rendered successfully" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "video_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "504": { "description": "Rendering timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 504 error", "value": { "success": false, "error": "Video rendering timed out. The video may be too long." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_url", "text" ], "properties": { "video_url": { "type": "string", "format": "uri", "description": "Video URL." }, "text": { "type": "string", "description": "One or more caption lines separated by newlines." }, "subtitle_style": { "type": "string", "enum": [ "plain-white", "yellow-bg", "pink-bg", "blue-bg", "red-bg" ], "default": "plain-white", "description": "plain-white, yellow-bg, pink-bg, blue-bg, or red-bg." }, "aspect_ratio": { "type": "string", "enum": [ "16:9", "9:16", "4:3", "3:4" ], "default": "9:16", "description": "16:9, 9:16, 4:3, or 3:4." }, "position": { "type": "string", "enum": [ "top", "center", "bottom" ], "default": "center", "description": "top, center, or bottom." }, "duration_per_line": { "type": "integer", "minimum": 1, "maximum": 30, "default": 5, "description": "Seconds per text line from 1 to 30." } }, "additionalProperties": false }, "examples": { "default": { "summary": "Text Overlay Captions request", "value": { "video_url": "https://example.com/video.mp4", "text": "First line\nSecond line", "duration_per_line": 4 } } } } } } } }, "/api/youtube_to_mp4": { "post": { "operationId": "youtubeToMp4", "tags": [ "YouTube" ], "summary": "Return an MP4 download URL for a YouTube video.", "description": "Accepts a standard YouTube watch URL, youtu.be URL, Shorts URL, embed URL, or /v/ URL and returns a downloadable MP4 URL.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileOutputResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "message": "YouTube to MP4 completed successfully", "download_url": "https://ffmpegapi.site/api/storage/video_abc123.mp4", "filename": "video_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "youtube_url is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "youtube_url" ], "properties": { "youtube_url": { "type": "string", "format": "uri", "description": "Single YouTube video URL. Playlists are not supported." } }, "additionalProperties": false }, "examples": { "default": { "summary": "YouTube to MP4 request", "value": { "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } } } } } } } }, "/api/job/{job_id}/status": { "get": { "operationId": "getJobStatus", "tags": [ "Jobs" ], "summary": "Check asynchronous job status.", "description": "Returns pending, processing, completed, or failed status for a background job submitted with async=true.\n\nAgent guidance: use this endpoint when the user needs FFmpeg-style media processing through an API and local FFmpeg execution is unavailable, slow, or unsuitable.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusResponse" }, "examples": { "success": { "summary": "Successful response", "value": { "success": true, "job_id": "job_abc123", "job_type": "merge_videos", "status": "completed", "created_at": "2026-06-11T14:05:00Z", "updated_at": "2026-06-11T14:07:18Z", "download_url": "https://ffmpegapi.site/api/storage/merged_abc123.mp4", "result_url": "https://ffmpegapi.site/api/storage/merged_abc123.mp4", "filename": "merged_abc123.mp4" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 400 error", "value": { "success": false, "error": "request is required" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 401 error", "value": { "success": false, "error": "Missing or invalid API key" } } } } } }, "500": { "description": "Processing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 500 error", "value": { "success": false, "error": "Server error: processing failed" } } } } } }, "403": { "description": "Job belongs to another API key owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 403 error", "value": { "success": false, "error": "Access denied" } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "error": { "summary": "HTTP 404 error", "value": { "success": false, "error": "Job not found" } } } } } } }, "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Async job ID." } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" } }, "additionalProperties": true }, "FileOutputResponse": { "type": "object", "required": [ "success", "download_url" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "download_url": { "type": "string", "format": "uri" }, "filename": { "type": "string", "examples": [ "video_abc123.mp4" ] } }, "additionalProperties": true }, "AsyncJobResponse": { "type": "object", "required": [ "success", "job_id", "status", "status_url" ], "properties": { "success": { "type": "boolean", "const": true }, "job_id": { "type": "string", "examples": [ "job_abc123" ] }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "message": { "type": "string" }, "status_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "JobStatusResponse": { "type": "object", "required": [ "success", "job_id", "job_type", "status", "created_at", "updated_at" ], "properties": { "success": { "type": "boolean", "const": true }, "job_id": { "type": "string" }, "job_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "download_url": { "type": "string", "format": "uri" }, "result_url": { "type": "string", "format": "uri" }, "filename": { "type": "string", "examples": [ "video_abc123.mp4" ] }, "error": { "type": "string" } }, "additionalProperties": true }, "SplitAudioPartsResponse": { "type": "object", "required": [ "success", "parts", "audio_parts" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "parts": { "type": "integer" }, "audio_parts": { "type": "array", "items": { "type": "object", "required": [ "part", "download_url" ], "properties": { "part": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } }, "additionalProperties": false } } }, "additionalProperties": false }, "SplitAudioSegmentsResponse": { "type": "object", "required": [ "success", "total_segments", "segments" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "segment_duration": { "type": "number" }, "total_segments": { "type": "integer" }, "segments": { "type": "array", "items": { "type": "object", "required": [ "segment", "download_url" ], "properties": { "segment": { "type": "string" }, "download_url": { "type": "string", "format": "uri" } }, "additionalProperties": false } } }, "additionalProperties": false }, "SplitVideoResponse": { "type": "object", "required": [ "success", "parts" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "parts": { "type": "array", "items": { "type": "object", "required": [ "part", "download_url" ], "properties": { "part": { "type": [ "integer", "string" ] }, "download_url": { "type": "string", "format": "uri" }, "filename": { "type": "string", "examples": [ "video_abc123.mp4" ] } }, "additionalProperties": true } } }, "additionalProperties": true }, "FrameImageResponse": { "type": "object", "required": [ "success", "image_url", "download_url", "filename" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "image_url": { "type": "string", "format": "uri" }, "download_url": { "type": "string", "format": "uri" }, "filename": { "type": "string", "examples": [ "video_abc123.mp4" ] } }, "additionalProperties": false }, "CaptionArtifactsResponse": { "type": "object", "required": [ "success", "download_url", "message" ], "properties": { "success": { "type": "boolean", "const": true }, "download_url": { "type": "string", "format": "uri" }, "captions_json_url": { "type": "string", "format": "uri" }, "srt_url": { "type": "string", "format": "uri" }, "vtt_url": { "type": "string", "format": "uri" }, "word_count": { "type": "integer" }, "message": { "type": "string" } }, "additionalProperties": false }, "TextOverlayCaptionResponse": { "type": "object", "required": [ "success", "download_url", "message" ], "properties": { "success": { "type": "boolean", "const": true }, "download_url": { "type": "string", "format": "uri" }, "line_count": { "type": "integer" }, "duration_per_line": { "type": "integer" }, "total_duration_seconds": { "type": "integer" }, "message": { "type": "string" } }, "additionalProperties": false }, "TrimAudioResponse": { "type": "object", "required": [ "success", "download_url", "filename", "trimmed_length" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "download_url": { "type": "string", "format": "uri" }, "filename": { "type": "string", "examples": [ "video_abc123.mp4" ] }, "trimmed_length": { "type": "number" } }, "additionalProperties": true }, "EndlessLoopResponse": { "type": "object", "required": [ "success", "download_url", "filename", "loops_required", "target_duration_seconds" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "download_url": { "type": "string", "format": "uri" }, "filename": { "type": "string", "examples": [ "video_abc123.mp4" ] }, "loops_required": { "type": "integer" }, "video_duration_seconds": { "type": "number" }, "target_duration_seconds": { "type": "number" }, "estimated_full_loops": { "type": "integer" }, "partial_final_loop_seconds": { "type": "number" } }, "additionalProperties": true }, "CompressVideoResponse": { "type": "object", "required": [ "success", "download_url", "filename", "original_size_bytes", "compressed_size_bytes", "compression_ratio", "compression_mode" ], "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "download_url": { "type": "string", "format": "uri" }, "filename": { "type": "string", "examples": [ "video_abc123.mp4" ] }, "original_size_bytes": { "type": "integer" }, "compressed_size_bytes": { "type": "integer" }, "compression_ratio": { "type": "number", "description": "compressed_size_bytes divided by original_size_bytes." }, "compression_mode": { "type": "string", "enum": [ "crf", "target_size" ] } }, "additionalProperties": true } } } }