Here’s a practical API design for subtitle burn-in and passthrough.

What it should do

Support two subtitle modes:

• Burn-in: render subtitles into the video frames
• Passthrough: keep subtitles as a separate track in the output file

You’ll usually want this in a media-processing service that accepts a video plus subtitle source and returns a new file or job id.

---

Core API shape

1) Create a subtitle processing job

POST /v1/subtitle-jobs

Request body

{
  "inputVideoUrl": "https://cdn.example.com/input.mp4",
  "subtitleUrl": "https://cdn.example.com/subs.srt",
  "mode": "burn_in",
  "outputFormat": "mp4",
  "language": "en",
  "style": {
    "fontFamily": "Arial",
    "fontSize": 28,
    "fontColor": "#FFFFFF",
    "outlineColor": "#000000",
    "outlineWidth": 2,
    "position": "bottom",
    "marginBottom": 40
  },
  "passthrough": {
    "codec": "copy",
    "container": "mp4"
  }
}

Mode values

• burn_in
• passthrough

---

Behavior by mode

Burn-in

• Subtitles are permanently rendered into the video
• Output is usually a re-encoded video
• Useful for social media, compatibility, or when you want subtitles always visible

Passthrough

• Subtitle track is preserved or muxed into the output container
• Video is not burned
• Useful when you want toggleable subtitles in players

---

Suggested response

{
  "jobId": "sub_123456",
  "status": "queued",
  "createdAt": "2026-10-28T12:00:00Z"
}

---

2) Check job status

GET /v1/subtitle-jobs/{jobId}

Response

{
  "jobId": "sub_123456",
  "status": "processing",
  "progress": 62,
  "inputVideoUrl": "https://cdn.example.com/input.mp4",
  "outputUrl": null,
  "error": null
}

Possible statuses:

• queued
• processing
• completed
• failed

---

3) Cancel a job

DELETE /v1/subtitle-jobs/{jobId}

---

4) Webhook callback

Useful for async processing.

Example payload

{
  "jobId": "sub_123456",
  "status": "completed",
  "outputUrl": "https://cdn.example.com/output.mp4"
}

---

Important implementation details

Subtitle input support

Allow:

• srt
• vtt
• ass
• embedded subtitle track reference

Output handling

For burn-in:

• likely use FFmpeg filter like subtitles or ass
• output must be re-encoded

For passthrough:

• if subtitle source is external, mux it into the output container
• if subtitle already exists in input, allow stream copy

---

Example FFmpeg logic

Burn-in

ffmpeg -i input.mp4 -vf "subtitles=subs.srt" -c:a copy output.mp4

Passthrough

ffmpeg -i input.mp4 -i subs.srt -c:v copy -c:a copy -c:s mov_text output.mp4

---

Recommended API fields

Job creation

• inputVideoUrl
• subtitleUrl
• mode
• outputFormat
• language
• style
• webhookUrl
• metadata

Optional advanced fields

• subtitleStreamIndex
• subtitleFormat
• burnInTimeRange
• videoCodec
• audioCodec
• container
• normalizeFonts
• forceSingleSubtitleTrack

---

Minimal OpenAPI-style schema

paths:
  /v1/subtitle-jobs:
    post:
      summary: Create a subtitle burn-in or passthrough job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - inputVideoUrl
                - subtitleUrl
                - mode
              properties:
                inputVideoUrl:
                  type: string
                subtitleUrl:
                  type: string
                mode:
                  type: string
                  enum: [burn_in, passthrough]
                outputFormat:
                  type: string
                  example: mp4
                language:
                  type: string
                webhookUrl:
                  type: string
                style:
                  type: object
      responses:
        "200":
          description: Job created

---

If you want, I can also provide:

1. a full OpenAPI 3.1 spec,
2. a Node.js/TypeScript implementation, or
3. an FFmpeg-backed architecture for this API.