Skip to content

Queue a subtitle burn-in job

POST
/assets/{id}/burn-subtitles

Queues a job meant to make a copy of the video with one subtitle track drawn into the picture. Burning in isn’t built yet: you get the job’s id, but no video is made, and when the server’s own worker runs the job, it fails it straight away.

Follow the job with GET /jobs/{id}, using job_id; its status shows what happened. Each request queues a new job, even for the same track.

Name the track with lang, which must match an existing track exactly; otherwise you get a 404. The asset’s type is checked first, so an asset that isn’t Video, Audio or Audiobook gets a 422, and an unknown id or an asset in the trash a 404. Audio and audiobook assets with a track pass these checks too.

Any signed-in account can queue this job for any such asset; ownership and edit rights aren’t checked. A body that isn’t valid JSON gets a plain-text 400, and server errors get a plain-text 500, not the JSON shown.

id
required
string format: uuid

The asset’s id.

object
lang
required

The language tag of the track to burn in, exactly as stored.

string

The job was queued. It doesn’t make a video yet.

object
job_id
required

The queued job’s id. Follow it with GET /jobs/{id}.

string format: uuid

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Request shape is valid but the action doesn’t apply (e.g. subtitles on a non-video/audio asset).

object
error
required

Human-readable error summary

string
Example
the request could not be completed