captions

The caption lines on a timeline, by action. generate cuts caption lines at sentences and phrases from the timeline’s speech (voiceover, dialogue or lyrics), plain white unless template or style sets a look, transcribing uploaded clips that have no words yet; it replaces any caption track, so a restyle is a re-run. import writes the user’s SRT or WebVTT file onto a clip’s file as its words and draws the lines, never transcribing. rewrite with no lines returns every line with its clip_id and limits; with lines and language it rewords the named lines in their slots; with regroup it moves the line breaks, word times kept, until the next generate. translate rewrites the lines in another language with a model, audio untouched. export returns the lines with format srt, vtt or txt, from a timeline or from one library item’s stored words. Re-voicing speech is change_language. Free, except generate on clips without words (cloud processing) and translate: credits.

POST

tools

captions

curl --request POST \
  --url https://eversince.ai/api/v1/tools/captions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clip_id": "<string>"
}
'

import requests

url = "https://eversince.ai/api/v1/tools/captions"

payload = { "clip_id": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({clip_id: '<string>'})
};

fetch('https://eversince.ai/api/v1/tools/captions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "ok": true,
  "data": {},
  "meta": {
    "request_id": "<string>",
    "cost": {},
    "cloud_processing": {
      "ran_on": "cloud",
      "minutes": 123,
      "charged_minutes": 123,
      "queued_minutes": 123,
      "left_minutes": 123,
      "held_minutes": 123,
      "bought_minutes": 123,
      "note": "<string>"
    }
  },
  "media": [
    {}
  ]
}

{
  "ok": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "suggested_action": "<string>",
    "cloud_processing": {
      "ran_on": "cloud",
      "minutes": 123,
      "charged_minutes": 123,
      "queued_minutes": 123,
      "left_minutes": 123,
      "held_minutes": 123,
      "bought_minutes": 123,
      "note": "<string>"
    }
  }
}

Authorizations

Authorization

string

header

required

An API key (es_live_…) from Settings, under API keys, or an OAuth access token.

Headers

Idempotency-Key

string

Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again.

x-workspace-id

string

The workspace this one call acts in, when it is not the default: for a key or a connected agent, one of the workspaces the user allowed it.

Body

application/json

action

enum<string>

required

Available options:

generate,

import,

rewrite,

translate,

export

timeline_id

string

The timeline. Every action but export with a ref needs it.

source

enum<string>

generate and export: which speech, voiceover, dialogue or music (lyrics); default is whichever the timeline has.

Available options:

voiceover,

dialogue,

music,

auto,

all

style

object

generate: color, activeColor, position, fontSize, fontFamily, fontWeight, fadeInFrames, fadeOutFrames, shadowEnabled, strokeEnabled, strokeColor, strokeWidth, backgroundColor, backgroundOpacity, emphasis ({words, color, emoji}), maxWords (a ceiling, default 6), maxChars (0 = no cap), closeGapMs (default 500), skipFillers (true leaves "um" and "uh" out of the lines, not the transcript; set by Social, Hook, Kinetic, Karaoke and One word). Unnamed fields are not kept; an unknown font is refused with the ones available.

Show child attributes

animation

object

generate: lineAnim, wordAnim. Unnamed fields are not kept.

Show child attributes

template

string

generate: a caption template as the base, sized to this timeline: one saved for this workspace, or built in: Subtitles, Kinetic, One word, Karaoke, Broadcast, Boxed, Story, Social, Hook. get_templates kind caption describes each. Social suits a talking head cut for a feed, Broadcast a landscape interview, Subtitles plain lines. style and animation override what they name.

save_template_as

string

generate: save the caption template this call lands under this name for later pieces. An existing name is overwritten.

Maximum string length: 60

file_text

string

import: the subtitle file's contents (SRT or WebVTT). Give this or ref.

Maximum string length: 2000000

ref

string

import: the library item that is the subtitle file (an uploaded .srt or .vtt). export: a library item whose stored words to export instead of a timeline's.

clip_id

string

import: the clip the subtitles belong to. Omitted: the one clip on the timeline still missing its words. regroup: the run's first line.

draw

boolean

import: draw the caption lines once the words land. Default true; false writes the words only.

cut

enum<string>

import: file (default) keeps each cue as the file wrote it; auto re-cuts the words into lines by the style's maxWords and maxChars.

Available options:

file,

auto

replace

boolean

import: write over words the clip or its file already has. Without it they are left alone.

lines

object[]

rewrite: the lines to reword, each once, by the clip_id a rewrite read returned, with its new text; the others stay. An unknown, empty or overlong line refuses the call and names it.

Required array length: 1 - 5000 elements

Show child attributes

regroup

string[]

rewrite: a run of whole lines with new breaks, one string per line, the same words in order. A changed word is refused and named.

Required array length: 1 - 5000 elements

Maximum string length: 1000

language

enum<string>

rewrite with lines: the language they are written in.

Available options:

en,

es,

fr,

de,

it,

pt,

ja,

ko,

zh,

ar,

hi,

ru,

nl,

pl,

sv,

da,

fi,

no,

cs,

sk,

hu,

ro,

bg,

hr,

uk,

el,

tr,

th,

vi,

id,

ms,

fil,

ta,

te,

ml,

kn,

bn,

gu,

mr,

pa,

he,

fa,

ur,

sw,

ha,

af,

ga,

cy,

is,

ca,

gl,

sl,

et,

lv,

lt,

sr,

bs,

mk,

ka,

hy,

az,

kk,

ne

target_language

enum<string>

translate: the language to write the lines in.

Available options:

en,

es,

fr,

de,

it,

pt,

ja,

ko,

zh,

ar,

hi,

ru,

nl,

pl,

sv,

da,

fi,

no,

cs,

sk,

hu,

ro,

bg,

hr,

uk,

el,

tr,

th,

vi,

id,

ms,

fil,

ta,

te,

ml,

kn,

bn,

gu,

mr,

pa,

he,

fa,

ur,

sw,

ha,

af,

ga,

cy,

is,

ca,

gl,

sl,

et,

lv,

lt,

sr,

bs,

mk,

ka,

hy,

az,

kk,

ne

as_new_timeline

boolean

rewrite and translate: write to a forked copy named " · " instead of this timeline.

format

enum<string>

export: srt (default), vtt, or txt: the words with no times.

Available options:

srt,

vtt,

txt

if_revision

The revision get_timeline returned. A stale one fails with revision_conflict instead of applying; so does no revision once a user edited the timeline in the app since this connection last read it.

context

string

Optional: one sentence shown to the user beside this action.

Maximum string length: 600

Response

Done, or a job started for work that runs longer (follow it with get_jobs).

any

required

data

object

required

Discovery

Timeline

Workspace

Library

Canvas

Generation

Research

Account

Models

Uploads

Webhooks

captions

Authorizations

Headers

Body

Response