API Documentation

Build powerful video processing workflows with our simple REST API

Getting Started

Authentication

All API requests require an API key. Get your API key from the dashboard after signing in.

Include your API key in the x-api-key header:

curl -X POST https://api.videocomposer.io/video/convert \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"input_url": "...", "out_format": "mp4"}'

Quick Start

1Get your API key from the dashboard
2Create a job with one of our video processing endpoints
3Check the job status using the job ID
4Download your processed video from the output URL

Rate Limits

API rate limits are enforced to ensure fair usage:

•100 requests per minute per API key
•1,000 requests per hour per API key
•10,000 requests per day per API key

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1620000000

Video Processing

POST

/video/convert

Convert Video Format

Convert a video to a different format with options for resizing and bitrate adjustment

Parameters

input_urlstring

required

— URL of the source video file

out_formatstring

required

— Output format: mp4, webm, or gif

widthnumber

— Output video width in pixels

heightnumber

— Output video height in pixels

bitrate_kbpsnumber

— Video bitrate in kilobits per second

Request Body

{
  "input_url": "https://cdn.videocomposer.io/sample_video1.mp4",
  "out_format": "webm",
  "width": 1280,
  "height": 720,
  "bitrate_kbps": 2000
}

Response Example

{
  "jobId": "54c0dd36-15e8-4b7f-bb6a-71c97938b84b",
  "status": "queued",
  "message": "Your job has been queued and will be processed shortly."
}

Code Examples

curl -X POST https://api.videocomposer.io/video/convert \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "input_url": "https://cdn.video",
    "out_format": "webm",
    "width": 1280,
    "height": 720
  }'

POST

/video/trim

Trim Video

Extract a portion of a video by specifying start and end times

Parameters

input_urlstring

required

— URL of the source video file

startstring

required

— Start time in HH:MM:SS.mmm format

endstring

required

— End time in HH:MM:SS.mmm format

Request Body

{
  "input_url": "https://cdn.video",
  "start": "00:00:10.000",
  "end": "00:00:20.000"
}

Response Example

{
  "jobId": "54c0dd36-15e8-4b7f-bb6a-71c97938b84b",
  "status": "queued",
  "message": "Your job has been queued and will be processed shortly."
}

Code Examples

curl -X POST https://api.videocomposer.io/video/trim \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "input_url": "https://cdn.video",
    "start": "00:00:10.000",
    "end": "00:00:20.000"
  }'

POST

/video/compose

Compose Videos

Combine multiple video clips with optional audio track and subtitles

Parameters

inputsarray

required

— Array of video URLs to concatenate

audio_urlstring

— URL of audio file to mix into the video

subtitle_urlstring

— URL of subtitle file (.srt) to burn in

crossfade_secnumber

— Duration of crossfade transition in seconds

Request Body

{
  "inputs": [
    "https://cdn.videocomposer.io/sample_video1.mp4",
    "https://cdn.videocomposer.io/sample_video2.mp4"
  ],
  "audio_url": "https://cdn.videocomposer.io/sample_audio.mp3",
  "subtitle_url": "https://cdn.videocomposer.io/sample_subtitle.srt",
  "crossfade_sec": 0.5
}

Response Example

{
  "jobId": "54c0dd36-15e8-4b7f-bb6a-71c97938b84b",
  "status": "queued",
  "message": "Your job has been queued and will be processed shortly."
}

Code Examples

curl -X POST https://api.videocomposer.io/video/compose \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "inputs": [
      "https://cdn.videocomposer.io/sample_video1.mp4",
      "https://cdn.videocomposer.io/sample_video2.mp4"
    ],
    "audio_url": "https://cdn.videocomposer.io/sample_audio.mp3"
  }'

POST

/video/overlay

Add Overlay

Add watermark image or text overlay to a video

Parameters

input_urlstring

required

— URL of the source video file

overlay_urlstring

— URL of image to use as watermark

textstring

— Text to render on video (use this or overlay_url)

xnumber

— X-coordinate for overlay position (default: 10)

ynumber

— Y-coordinate for overlay position (default: 10)

opacitynumber

— Overlay opacity from 0 to 1 (default: 0.8)

font_sizenumber

— Font size for text overlays (default: 72)

Request Body

{
  "input_url": "https://cdn.video",
  "text": "© 2024 My Company",
  "x": 20,
  "y": 20,
  "font_size": 36,
  "opacity": 0.9
}

Response Example

{
  "jobId": "54c0dd36-15e8-4b7f-bb6a-71c97938b84b",
  "status": "queued",
  "message": "Your job has been queued and will be processed shortly."
}

Code Examples

curl -X POST https://api.videocomposer.io/video/overlay \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "input_url": "https://cdn.video",
    "text": "© 2024 My Company",
    "x": 20,
    "y": 20,
    "font_size": 72,
    "opacity": 0.9
  }'

POST

/video/thumbnail

Generate Thumbnail

Create a thumbnail from a video - single frame, animated GIF, or sprite sheet

Parameters

input_urlstring

required

— URL of the source video file

modestring

required

— Thumbnail type: frame, sprite, or gif

timestampstring

— Timestamp for frame mode in HH:MM:SS.mmm

fpsnumber

— Frames per second for sprite or gif mode

Request Body

{
  "input_url": "https://cdn.video",
  "mode": "frame",
  "timestamp": "00:00:15.000"
}

Response Example

{
  "jobId": "54c0dd36-15e8-4b7f-bb6a-71c97938b84b",
  "status": "queued",
  "message": "Your job has been queued and will be processed shortly."
}

Code Examples

curl -X POST https://api.videocomposer.io/video/thumbnail \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "input_url": "https://cdn.video",
    "mode": "frame",
    "timestamp": "00:00:15.000"
  }'

GET

/video/validate

Validate Media

Validate media files to ensure they are accessible and of the expected type

Parameters

input_urlstring

required

— URL of the media file to validate

expected_typestring

— Expected type: video, audio, image, or subtitle

Response Example

{
  "valid": true,
  "fileType": "video",
  "contentType": "video/mp4",
  "contentLength": 50000000,
  "supportedExtensions": {
    "video": [
      "mp4",
      "webm"
    ],
    "audio": [
      "mp3"
    ],
    "image": [
      "jpg",
      "jpeg",
      "png",
      "gif",
      "bmp",
      "tiff",
      "webp"
    ],
    "subtitle": [
      "srt"
    ]
  }
}

Code Examples

curl -X GET "https://api.videocomposer.io/video/validate?input_url=https://cdn.video&expected_type=video" \
  -H "x-api-key: YOUR_API_KEY"

Job Management

GET

/jobs/:id

Check Job Status

Retrieve the status and details of a video processing job

Parameters

idstring

required

— The job ID returned from a video processing request

Response Example

{
  "id": "54c0dd36-15e8-4b7f-bb6a-71c97938b84b",
  "state": "done",
  "input_url": "https://videocomposer.io/video.mp4",
  "output_url": "https://videocomposer.io/outputs/54c0dd36-15e8-4b7f-bb6a-71c97938b84b.mp4",
  "error": null,
  "created_at": "2025-06-08T01:47:46.434Z"
}

Code Examples

curl -X GET "https://api.videocomposer.io/jobs/54c0dd36-15e8-4b7f-bb6a-71c97938b84b" \
  -H "x-api-key: YOUR_API_KEY"

Webhooks

Configure webhooks to receive real-time notifications when your video processing jobs complete.

Webhook Configuration

Each API key can have one webhook URL configured. When a job completes (successfully or with an error), we'll send a POST request to your webhook URL with the job details.

Webhook Payload

{
  "jobId": "54c0dd36-15e8-4b7f-bb6a-71c97938b84b",
  "state": "done",
  "inputUrl": "https://cdn.video",
  "outputUrl": "https://videocomposer.io/outputs/54c0dd36-15e8-4b7f-bb6a-71c97938b84b.mp4",
  "error": null,
  "createdAt": "2025-06-08T01:47:46.434Z",
  "completedAt": "2025-06-08T01:48:12.123Z",
  "processingTimeMs": 26689
}

Webhook Headers

Content-Type: application/json
User-Agent: VideoComposer-Webhook/1.0
X-Webhook-Event: job.completed
X-Webhook-Timestamp: 2025-06-08T01:48:12.123Z
X-Webhook-Signature: sha256=d2e58b45f8c6e7a9d4b3c1a8e9f6d3b2a7c4e8f9a2b5c7d8e3f4a6b7c8d9e1f2

Retry Policy

•We'll retry failed webhook deliveries up to 3 times
•Retries use exponential backoff: 1 minute, 5 minutes, then 15 minutes
•Webhooks have a 30 second timeout
•Only 2xx status codes are considered successful

Security

If you provide a webhook secret when configuring your webhook, we'll use it to sign the payload with HMAC-SHA256. The signature is included in the X-Webhook-Signature header.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

PUT

/webhooks

Update Webhook Configuration

Configure or update the webhook URL for your API key

Request Body

{
  "webhook_url": "https://your-domain.com/webhook",
  "webhook_secret": "your-secret-key-min-16-chars"
}

Response Example

{
  "success": true,
  "message": "Webhook updated successfully",
  "webhook_url": "https://your-domain.com/webhook"
}

Code Examples

curl -X PUT https://api.videocomposer.io/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "webhook_url": "https://your-domain.com/webhook",
    "webhook_secret": "your-secret-key-min-16-chars"
  }'

GET

/webhooks

Get Webhook Configuration

Retrieve the current webhook configuration for your API key

Response Example

{
  "webhook_url": "https://your-domain.com/webhook",
  "configured": true
}

Code Examples

curl -X GET https://api.videocomposer.io/webhooks \
  -H "x-api-key: YOUR_API_KEY"

POST

/webhooks/test

Test Webhook

Send a test payload to a webhook URL to verify it's working correctly

Request Body

{
  "webhook_url": "https://your-domain.com/webhook",
  "webhook_secret": "your-secret-key-min-16-chars"
}

Response Example

{
  "success": true,
  "message": "Webhook test successful",
  "responseTime": 123
}

Code Examples

curl -X POST https://api.videocomposer.io/webhooks/test \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "webhook_url": "https://your-domain.com/webhook",
    "webhook_secret": "your-secret-key-min-16-chars"
  }'

Account

GET

/usage

Get Credit Balance

Check your current credit balance

Response Example

{
  "credits": 500
}

Code Examples

curl -X GET "https://api.videocomposer.io/usage" \
  -H "x-api-key: YOUR_API_KEY"

Sample Videos

Use these sample videos for testing the API

https://cdn.videocomposer.io/sample_video1.mp4https://cdn.videocomposer.io/sample_video2.mp4https://cdn.videocomposer.io/sample_video3.mp4https://cdn.videocomposer.io/sample_video4.mp4https://cdn.videocomposer.io/sample_video5.mp4