Documentation

Introduction

OtomatikEdit allows you to programmatically create stunning videos from images and audio.

RESTful API

Standard HTTP methods and clear JSON responses for easy integration.

Cloud Rendering

Heavy lifting is done on our servers. You just get the final MP4.

Download API Collections

Import our API collections into your favorite API client.

Bruno Collection Postman Collection

Authentication

Authenticate your requests using your API key.

Keep your API keys secure. Do not share them in client-side code or public repositories.

Authorization Header

Include the key in the Authorization header of your requests.

bash

Authorization: Bearer YOUR_API_KEY_HERE

Quick Start

Create your first video in minutes.

Media File Limits

Images: max 10MB | Videos: max 200MB | ZIP: max 200MB | Music: max 50MB

bash

# Example 1: Basic video with images and music
curl -X POST https://api.otomatikedit.com/api/video/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "media=@image1.jpg" \
  -F "media=@image2.jpg" \
  -F "media=@video1.mp4" \
  -F "music=@background.mp3" \
  -F "duration=15" \
  -F "transition=fade" \
  -F "audioFadeIn=2" \
  -F "audioFadeOut=3" \
  -F "aspectPreset=portrait-9-16" \
  -F "videoMuted=false" \
  -F "duckingMusicVolume=0.6" \
  -F "duckingRatio=4" \
  -F "loopMusic=true" \
  -F "title=My Awesome Video"

# Example 2: Using ZIP archive and music URL
curl -X POST https://api.otomatikedit.com/api/video/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "media=@photos.zip" \
  -F "musicUrl=https://example.com/audio.mp3" \
  -F "duration=30" \
  -F "aspectPreset=portrait-9-16"

API Reference

POST/api/video/create

Initiate a new video generation job.

Parameters

mediaRequired

file[]

Repeat this field multiple times (once per file). Images (JPG, PNG, WEBP, max 10MB each), Videos (MP4, MOV, AVI, WEBM, max 200MB each), or ZIP archives (max 200MB). You can mix images and videos. ZIP files are automatically extracted and only images/videos inside are processed. Use "photos" for backward compatibility.

music

file

Uploaded audio file (MP3, WAV, M4A, max 50MB). Cannot be used with musicUrl.

musicUrl

string

Direct URL to an audio file (HTTP/HTTPS). The file will be downloaded automatically. Cannot be used with music.

instrumental

file

Uploaded instrumental audio file (MP3, WAV, M4A, max 50MB). Mixed at reduced volume. Cannot be used with instrumentalUrl.

instrumentalUrl

string

Direct URL to an instrumental audio file (HTTP/HTTPS). The file will be downloaded automatically and mixed at reduced volume. Cannot be used with instrumental.

instrumentalVolume

number

Instrumental track volume (0-1, default: 0.15). Only used when instrumental or instrumentalUrl is provided.

durationRequired

number

Total duration in seconds (10-300)

transition

string

Transition effect name (default: fade). Options: none, fade, crossfade, dissolve, wipeleft, wiperight, slideup, slidedown, random

audioFadeIn

number

Audio fade in duration in seconds (0-10, default: 0)

audioFadeOut

number

Audio fade out duration in seconds (0-10, default: 3)

aspectPreset

string

Output aspect ratio preset (default: landscape-16-9). Options: landscape-16-9, portrait-9-16, square-1-1, vertical-4-5, linkedin-191-100

title

string

Optional title for the video job (max 200 characters)

videoMuted

boolean

If true, mute all video audio and keep only music or vocal track (default: true). If false, enable audio ducking to mix video audio with music or vocal track.

duckingMusicVolume

number

Music or vocal track volume when ducking is enabled (0-1, default: 0.65). Only used when videoMuted is false.

duckingRatio

number

Ducking compression ratio (2-10, default: 3). Higher values = more aggressive ducking. Only used when videoMuted is false. With default values (65% volume, ratio 3), music drops to ~22% when video plays.

loopMusic

boolean

If true, loop music to match video duration (default: false). If false, music plays once and stops (may be shorter than video).

musicStartTime

number

Music trim start time in seconds. Use to skip the beginning of the music track. Must be less than musicEndTime if both are provided.

musicEndTime

number

Music trim end time in seconds. Use to cut the music before it ends. Must be greater than musicStartTime if both are provided.

subtitle

file

Subtitle file (SRT or ASS format, max 5MB). Subtitles will be placed at the bottom of the video. Cannot be used with subtitleContent or autoGenerateSubtitles.

subtitleContent

string

Subtitle content in SRT format (text). Subtitles will be placed at the bottom of the video. Cannot be used with subtitle file or autoGenerateSubtitles.

autoGenerateSubtitles

boolean

If true, automatically generate subtitles from video audio using AI. Cannot be used with subtitle or subtitleContent.

subtitleLanguage

string

Language for auto-generated subtitles (default: "auto"). Options: "auto", "en", "fr", "es", "de", "it", "pt", "nl", "ja", "ko", "zh", etc.

subtitleOffset

number

Subtitle timing offset in seconds (default: 0). Positive values delay subtitles, negative values advance them.

jobId

string

Optional custom job identifier (must be valid UUID format). If not provided, a UUID will be generated automatically.

animation

string

Ken Burns animation effect for images (default: none). Options: none, zoom-in, zoom-out, pan-left, pan-right, pan-up, pan-down, random. Only applies to images, not videos.

audioSpectrum

string

Audio spectrum visualization overlay at the bottom of the video (default: none). Options: none, waveform (audio waveform line), spectrogram (frequency spectrogram), bars (EQ-style frequency bars). Occupies 15% of video height.

Example Request

bash

curl -X POST https://api.otomatikedit.com/api/video/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "media=@image1.jpg" \
  -F "media=@image2.jpg" \
  -F "media=@video1.mp4" \
  -F "music=@background.mp3" \
  -F "duration=30" \
  -F "transition=fade" \
  -F "audioFadeIn=0" \
  -F "audioFadeOut=3" \
  -F "aspectPreset=portrait-9-16" \
  -F "videoMuted=false" \
  -F "duckingMusicVolume=0.6" \
  -F "duckingRatio=4" \
  -F "loopMusic=true" \
  -F "musicStartTime=5" \
  -F "musicEndTime=60" \
  -F "autoGenerateSubtitles=true" \
  -F "subtitleLanguage=en" \
  -F "audioSpectrum=bars" \
  -F "title=My Video"

GET/api/video/status/:jobId

Check the processing status of a job.

Parameters

jobIdRequired

string

The ID returned from the creation endpoint.

Example Request

bash

curl https://api.otomatikedit.com/api/video/status/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/video/download/:jobId

Download the final generated video file.

Parameters

jobIdRequired

string

The ID of the completed job.

Example Request

bash

curl -O https://api.otomatikedit.com/api/video/download/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/api/video/health

Check API health status and verify FFmpeg installation.

Response

Returns API health status including:

FFmpeg version and installation status
Server status and uptime
Environment information

Example Request

bash

curl https://api.otomatikedit.com/api/video/health

GET/api/video/jobs

Get a list of all video creation jobs.

Response

Returns an array of all jobs with:

Job metadata and status
Progress information
Total count

Example Request

bash

curl https://api.otomatikedit.com/api/video/jobs \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE/api/video/:jobId

Delete a job and all associated files.

Parameters

jobIdRequired

string

The ID of the job to delete.

Deletes:

Job record
Uploaded photos and videos
Uploaded music
Generated video file

Example Request

bash

curl -X DELETE https://api.otomatikedit.com/api/video/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

PreConfig Video API

Manage video pre-configurations to save and reuse your video settings. All endpoints require Firebase authentication.

POST/api/preconfig-video

Create a new video pre-configuration.

Request Body

subjectRequired

string

Subject or title of the pre-configuration

typeRequired

string

Content type: "videos", "images", or "mix"

ratioRequired

string

Aspect ratio: "9:16", "16:9", or "1:1"

photos

number

Number of photos (required if type is "images" or "mix")

videos

number

Number of videos (required if type is "videos" or "mix")

clip_durRequired

string

Clip duration in seconds: "4", "8", or "12"

total_durRequired

string

Total duration: "15", "30", "60", "120", "180", or "300" seconds

audioRequired

string

Audio type: "voice", "music", or "none"

voice_text

string

Text for voice-over (required if audio is "voice")

voice_mode

string

Voice mode: "manual" or "auto"

schedule

object

Schedule configuration (optional)

schedule.enabled

boolean

Enable scheduled video generation

schedule.videosPerDay

number

Number of videos to generate per day (validated against monthly quota)

Example Request

bash

curl -X POST https://api.otomatikedit.com/api/preconfig-video \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "My Video Preset",
    "type": "mix",
    "ratio": "9:16",
    "photos": 5,
    "videos": 2,
    "clip_dur": "8",
    "total_dur": "60",
    "audio": "voice",
    "voice_text": "Welcome to my channel",
    "voice_mode": "auto",
    "schedule": {
      "enabled": true,
      "videosPerDay": 3
    }
  }'

GET/api/preconfig-video

Get all pre-configurations for the authenticated user.

Response

Returns an array of pre-configurations sorted by creation date (newest first).

Response includes:

All pre-configuration fields
Creation and update timestamps
Schedule configuration if enabled

Example Request

bash

curl https://api.otomatikedit.com/api/preconfig-video \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN"

GET/api/preconfig-video/:id

Get a specific pre-configuration by ID.

Parameters

idRequired

string

The pre-configuration ID.

Example Request

bash

curl https://api.otomatikedit.com/api/preconfig-video/abc123 \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN"

PUT/api/preconfig-video/:id

Update an existing pre-configuration.

Parameters

idRequired

string

The pre-configuration ID to update.

Request body is the same as POST /api/preconfig-video

Example Request

bash

curl -X PUT https://api.otomatikedit.com/api/preconfig-video/abc123 \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Updated Preset",
    "type": "videos",
    "ratio": "16:9",
    "videos": 3,
    "clip_dur": "12",
    "total_dur": "120",
    "audio": "music"
  }'

DELETE/api/preconfig-video/:id

Delete a pre-configuration.

Parameters

idRequired

string

The pre-configuration ID to delete.

Example Request

bash

curl -X DELETE https://api.otomatikedit.com/api/preconfig-video/abc123 \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN"

Aspect Ratios

Landscape

landscape-16-9

16:9YouTube, TV

Portrait

portrait-9-16

9:16TikTok, Reels

Square

square-1-1

1:1Instagram Post

Vertical

vertical-4-5

4:5FB/IG Ads

Twitter

linkedin-191-100

1.91:1Twitter Card

Transitions

random

fade

crossfade

dissolve

wipeleft

wiperight

slideup

slidedown

none

Animations (Ken Burns)

Add cinematic movement to your images with Ken Burns animations.

none

None

Static image, no movement

zoom-in

Zoom In

Gradual zoom towards center

zoom-out

Zoom Out

Pull back to reveal image

pan-left

Pan Left

Horizontal pan to the left

pan-right

Pan Right

Horizontal pan to the right

pan-up

Pan Up

Vertical pan upwards

pan-down

Pan Down

Vertical pan downwards

random

Random

Mix of different animations

Usage Example

bash

curl -X POST https://api.otomatikedit.com/api/video/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "media=@image1.jpg" \
  -F "media=@image2.jpg" \
  -F "music=@background.mp3" \
  -F "duration=30" \
  -F "animation=zoom-in"

Audio Spectrum

Add a real-time audio visualization overlay at the bottom of your video.

waveform

Waveform

Audio waveform line that moves with the music amplitude

spectrogram

Spectrogram

Frequency intensity over time as a color gradient

bars

EQ Bars

Equalizer-style frequency bars visualization

Technical Details

Height

15% of video

Position

Bottom of frame

Background

50% opacity black

Primary Color

#00FF88

Secondary Color

#00AAFF

Frame Rate

30 fps

Usage Example

bash

curl -X POST https://api.otomatikedit.com/api/video/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "media=@image1.jpg" \
  -F "media=@image2.jpg" \
  -F "music=@background.mp3" \
  -F "duration=30" \
  -F "audioSpectrum=bars"

Quick Start

Create your first video in minutes.

Media File Limits

Images: max 10MB | Videos: max 200MB | ZIP: max 200MB | Music: max 50MB

bash

# Example 1: Basic video with images and music
curl -X POST https://api.otomatikedit.com/api/video/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "media=@image1.jpg" \
  -F "media=@image2.jpg" \
  -F "media=@video1.mp4" \
  -F "music=@background.mp3" \
  -F "duration=15" \
  -F "transition=fade" \
  -F "audioFadeIn=2" \
  -F "audioFadeOut=3" \
  -F "aspectPreset=portrait-9-16" \
  -F "videoMuted=false" \
  -F "duckingMusicVolume=0.6" \
  -F "duckingRatio=4" \
  -F "loopMusic=true" \
  -F "title=My Awesome Video"

# Example 2: Using ZIP archive and music URL
curl -X POST https://api.otomatikedit.com/api/video/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "media=@photos.zip" \
  -F "musicUrl=https://example.com/audio.mp3" \
  -F "duration=30" \
  -F "aspectPreset=portrait-9-16"

curl -X POST https://api.otomatikedit.com/api/video/create \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "media=@image1.jpg" \ -F "media=@image2.jpg" \ -F "media=@video1.mp4" \ -F "music=@background.mp3" \ -F "duration=30" \ -F "transition=fade" \ -F "audioFadeIn=0" \ -F "audioFadeOut=3" \ -F "aspectPreset=portrait-9-16" \ -F "videoMuted=false" \ -F "duckingMusicVolume=0.6" \ -F "duckingRatio=4" \ -F "loopMusic=true" \ -F "musicStartTime=5" \ -F "musicEndTime=60" \ -F "autoGenerateSubtitles=true" \ -F "subtitleLanguage=en" \ -F "audioSpectrum=bars" \ -F "title=My Video"

curl -X POST https://api.otomatikedit.com/api/preconfig-video \ -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "subject": "My Video Preset", "type": "mix", "ratio": "9:16", "photos": 5, "videos": 2, "clip_dur": "8", "total_dur": "60", "audio": "voice", "voice_text": "Welcome to my channel", "voice_mode": "auto", "schedule": { "enabled": true, "videosPerDay": 3 } }'

curl -X PUT https://api.otomatikedit.com/api/preconfig-video/abc123 \ -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "subject": "Updated Preset", "type": "videos", "ratio": "16:9", "videos": 3, "clip_dur": "12", "total_dur": "120", "audio": "music" }'

Animations (Ken Burns)

Add cinematic movement to your images with Ken Burns animations.

none

None

Static image, no movement

zoom-in

Zoom In

Gradual zoom towards center

zoom-out

Zoom Out

Pull back to reveal image

pan-left

Pan Left

Horizontal pan to the left

pan-right

Pan Right

Horizontal pan to the right

pan-up

Pan Up

Vertical pan upwards

pan-down

Pan Down

Vertical pan downwards

random

Random

Mix of different animations

Usage Example

bash

curl -X POST https://api.otomatikedit.com/api/video/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "media=@image1.jpg" \
  -F "media=@image2.jpg" \
  -F "music=@background.mp3" \
  -F "duration=30" \
  -F "animation=zoom-in"

Audio Spectrum

Add a real-time audio visualization overlay at the bottom of your video.

waveform

Waveform

Audio waveform line that moves with the music amplitude

spectrogram

Spectrogram

Frequency intensity over time as a color gradient

bars

EQ Bars

Equalizer-style frequency bars visualization

Technical Details

Height

15% of video

Position

Bottom of frame

Background

50% opacity black

Primary Color

#00FF88

Secondary Color

#00AAFF

Frame Rate

30 fps

Usage Example

bash

curl -X POST https://api.otomatikedit.com/api/video/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "media=@image1.jpg" \
  -F "media=@image2.jpg" \
  -F "music=@background.mp3" \
  -F "duration=30" \
  -F "audioSpectrum=bars"