> ## Documentation Index > Fetch the complete documentation index at: https://docs.eversince.ai/llms.txt > Use this file to discover all available pages before exploring further. # captions > The caption lines on a timeline, by action. generate builds caption lines from the timeline's speech (voiceover, dialogue or lyrics) in a template or a style, transcribing uploaded clips that have no words yet; it replaces any caption track already there, so a restyle is a re-run. import writes an SRT or WebVTT file the user has onto a clip 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 replaces the words in place, slots and word timing kept. translate rewrites the lines in another language with a model, audio untouched. export returns the lines as SRT, VTT or plain text, from a timeline or from one library item's stored words. Nothing here re-voices speech: that is change_language. Free, except generate on clips without words (cloud processing) and translate: credits. ## OpenAPI ````yaml /openapi.json post /tools/captions openapi: 3.1.0 info: title: Eversince API version: '1' description: >- Every Eversince tool as one POST call, plus the routes beside them: the tool list, account and keys, uploads, webhooks and models. The prose is at https://docs.eversince.ai. servers: - url: https://eversince.ai/api/v1 security: - bearer: [] tags: - name: Discovery description: The tool list, the same on the MCP server, the REST API and the CLI. - name: Workspace description: Jobs, balances, settings, templates, skills and the overview. - name: Library description: >- Items, search, import, reading media, comments, boards, calendars, the brand kit and public links. - name: Timeline description: 'Video editing: timelines, clips, captions, sound, language and rendering.' - name: Canvas description: 'Still editing: canvases, slides, layers and rendering.' - name: Generation description: Image, video and audio generation, upscaling, cutouts and models. - name: Research description: 'What platforms publish: pulling and keeping posts.' - name: Account description: Balances, keys, workspaces and script sessions. - name: Uploads description: Files into the library by presigned upload or by URL. - name: Webhooks description: Job results posted to a URL as they complete. - name: Models description: Generation models and cost estimates. paths: /tools/captions: post: tags: - Timeline summary: captions description: >- The caption lines on a timeline, by action. generate builds caption lines from the timeline's speech (voiceover, dialogue or lyrics) in a template or a style, transcribing uploaded clips that have no words yet; it replaces any caption track already there, so a restyle is a re-run. import writes an SRT or WebVTT file the user has onto a clip 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 replaces the words in place, slots and word timing kept. translate rewrites the lines in another language with a model, audio untouched. export returns the lines as SRT, VTT or plain text, from a timeline or from one library item's stored words. Nothing here re-voices speech: that is change_language. Free, except generate on clips without words (cloud processing) and translate: credits. operationId: captions parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/WorkspaceId' requestBody: required: true content: application/json: schema: type: object properties: action: type: string enum: - generate - import - rewrite - translate - export timeline_id: description: The timeline. Every action but export with a ref needs it. type: string source: description: >- generate and export: which speech, voiceover, dialogue or music (lyrics); default is whichever the timeline has. type: string enum: - voiceover - dialogue - music - auto - all style: description: >- generate: color, activeColor, position, fontSize, fontFamily, fontWeight, fadeInFrames, fadeOutFrames, shadowEnabled, strokeEnabled, strokeColor, strokeWidth, backgroundColor, backgroundOpacity, emphasis ({words, color, emoji}), maxWords (default 6), maxChars (0 = no cap), closeGapMs (default 500). Unnamed fields are not kept; an unknown font is refused with the ones available. type: object propertyNames: type: string additionalProperties: {} animation: description: 'generate: lineAnim, wordAnim. Unnamed fields are not kept.' type: object propertyNames: type: string additionalProperties: {} template: description: >- 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. type: string save_template_as: description: >- generate: save the caption template this call lands under this name for later pieces. An existing name is overwritten. type: string maxLength: 60 file_text: description: >- import: the subtitle file's contents (SRT or WebVTT). Give this or ref. type: string maxLength: 2000000 ref: description: >- 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. type: string clip_id: description: >- import: the clip the subtitles belong to. Omitted: the one clip on the timeline still missing its words. type: string draw: description: >- import: draw the caption lines once the words land. Default true; false writes the words only. type: boolean cut: description: >- 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. type: string enum: - file - auto replace: description: >- import: write over words the clip already has. Without it a clip that knows its words is left alone. type: boolean lines: description: >- rewrite: every caption line once, by the clip_id a rewrite read returned, with its new text. A missing, unknown, empty or overlong line refuses the whole call and names it. minItems: 1 maxItems: 5000 type: array items: type: object properties: clip_id: type: string text: type: string maxLength: 1000 required: - clip_id - text language: description: 'rewrite with lines: the language they are written in.' type: string enum: - 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: description: 'translate: the language to write the lines in.' type: string enum: - 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: description: >- rewrite and translate: write to a forked copy named " · " instead of this timeline. type: boolean format: description: 'export: default srt. txt is the words with no times.' type: string enum: - srt - vtt - txt if_revision: description: >- 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. anyOf: - type: string - type: integer context: description: 'Optional: one sentence shown to the user beside this action.' type: string maxLength: 600 required: - action responses: '200': description: >- Done, or a job started for work that runs longer (follow it with get_jobs). content: application/json: schema: type: object required: - ok - data - meta properties: ok: const: true data: type: object additionalProperties: true meta: type: object properties: request_id: type: string cost: $ref: '#/components/schemas/Cost' cloud_processing: $ref: '#/components/schemas/CloudProcessing' media: type: array items: type: object additionalProperties: true default: $ref: '#/components/responses/Error' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string description: >- Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again. WorkspaceId: name: x-workspace-id in: header required: false schema: type: string description: The workspace this one call acts in, when it is not the key's own. schemas: Cost: type: object description: AI credits the call cost. additionalProperties: true CloudProcessing: type: object description: Cloud processing the call used, and what is left. properties: ran_on: const: cloud minutes: type: number queued_minutes: type: number left_minutes: type: number bought_minutes: type: number note: type: string Error: type: object required: - ok - error properties: ok: const: false error: type: object required: - code - message - retryable properties: code: type: string message: type: string description: What went wrong, in words to act on. retryable: type: boolean suggested_action: type: string description: The next step that works. cloud_processing: $ref: '#/components/schemas/CloudProcessing' responses: Error: description: The call was refused or failed. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearer: type: http scheme: bearer description: >- An API key (es_live_…) from Settings, under API keys, or an OAuth access token. ````