Developers

API DOCS

Add AI-powered subtitles to videos programmatically. The SubSpark API accepts a video file and returns a subtitled MP4.

OVERVIEW

The SubSpark API lets you add AI subtitles to videos from your own code. Send a video file, get back a subtitled MP4 — same pipeline as the web app.

Base URL

https://subspark.net

API version

Format

multipart/form-data

Response

video/mp4

⚡ API access requires a Pro or Business plan. View plans →

AUTHENTICATION

All API requests must include your API key in the Authorization header using Bearer token format.

Authorization: Bearer sk_live_your_api_key_here

Generate and manage your API keys in the Dashboard → API section. Keys start with sk_live_.

Security: Never expose your API key in client-side code or public repositories. Treat it like a password.

ENDPOINT

POST/api/v1/subtitles

Processes a video file and returns a new MP4 with subtitles burned in. The subtitles are transcribed automatically using AI and rendered in the style you choose.

REQUEST PARAMETERS

fileFilerequired

The video file to process. Supported formats: MP4, MOV, AVI, MKV. Max size: 500MB.

stylestring

Subtitle style name. Default: classic. Options: karaoke, neon, bold, minimal, classic, fire, ice, shadow, retro, cinema, pop, ghost.

positionstring

Subtitle position on screen. Default: bottom. Options: top, center, bottom.

font_sizenumber

Font size override. Default: 0 (uses style default).

RESPONSE

On success, the API returns the processed video as a binary video/mp4 stream.

HeaderValueDescription

Content-Typevideo/mp4Always video/mp4

Content-Dispositionattachment; filename="subtitled.mp4"Suggested filename

X-Languagee.g. en, es, autoDetected language of the audio

ERROR CODES

400

Bad Request

Missing or invalid request parameters

401

Unauthorized

Missing, invalid, or revoked API key

403

Forbidden

Your plan does not include API access

429

Too Many Requests

Rate limit exceeded

502

Bad Gateway

Processing service returned an error

503

Service Unavailable

Processing service is temporarily unavailable

Error responses are JSON with an error field:

{ "error": "Invalid or revoked API key" }

EXAMPLES

cURL

curl -X POST https://subspark.net/api/v1/subtitles \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "file=@my_video.mp4" \
  -F "style=bold" \
  -F "position=bottom" \
  --output subtitled.mp4

JavaScript / Node.js

const fs = require('fs')
const FormData = require('form-data')

const form = new FormData()
form.append('file', fs.createReadStream('video.mp4'))
form.append('style', 'bold')
form.append('position', 'bottom')

const res = await fetch('https://subspark.net/api/v1/subtitles', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    ...form.getHeaders(),
  },
  body: form,
})

if (!res.ok) {
  const err = await res.json()
  throw new Error(err.error)
}

const buffer = await res.arrayBuffer()
fs.writeFileSync('subtitled.mp4', Buffer.from(buffer))
console.log('Done! Language:', res.headers.get('X-Language'))

Python

import requests

with open('video.mp4', 'rb') as f:
    res = requests.post(
        'https://subspark.net/api/v1/subtitles',
        headers={'Authorization': 'Bearer sk_live_your_api_key'},
        files={'file': f},
        data={'style': 'bold', 'position': 'bottom'},
    )

res.raise_for_status()
with open('subtitled.mp4', 'wb') as out:
    out.write(res.content)
print('Language:', res.headers.get('X-Language'))

RATE LIMITS

The API is rate-limited per API key. If you exceed the limit, you will receive a 429 Too Many Requests response.

Pro10 requests / minute

Business60 requests / minute

Processing time depends on video length. Large files may take 30–120 seconds. Set an appropriate timeout.

Questions or issues? hello@subspark.net or visit the contact page.