Skip to main content
POST
Render a video

Authorizations

Authorization
string
header
required

A workspace API key.

Body

application/json

Send story and nothing else is required — the prose is the input, and the video is filed under an id derived from it. videoId, slug and topic are the other way in: they name something already in this deployment's catalogue and each needs a domain to be read against. Exactly one of the four.

domain
enum<string>

Which library the subject is read from. Optional, and not something to send when you are supplying your own text: with story it defaults to stories, the domain that renders prose. Required with videoId, slug or topic, because those name an entry in one particular catalogue and mean nothing without it.

Available options:
algorithms,
science,
course,
stories,
chess,
howto,
ugc
videoId
string

An entry already in this deployment's catalogue for domain. You do not need one to render your own writing — send story instead.

Required string length: 1 - 300
slug
string

A catalogue entry by slug. See videoId.

Required string length: 1 - 300
topic
string

A catalogue subject by name, for the domains that resolve one. See videoId.

Required string length: 1 - 300
story
string

Your own prose, narrated and rendered as-is — an article, a lesson, a chapter. This is the whole input: the video is filed under an id generated from the text, so nothing has to exist on our side first. Up to 40,000 characters.

Required string length: 1 - 40000
title
string

What to call the finished video. Derived from the text when omitted.

Required string length: 1 - 200
aspect
enum<string>

horizontal for long-form, vertical for a feed. Defaults to horizontal.

Available options:
horizontal,
vertical
quality
enum<string>

Low, medium, high or 4K. Defaults to m. Higher costs more wall-clock, not more credits.

Available options:
l,
m,
h,
k
renderer
enum<string>

How the picture is made: motif for animated typography and diagrams, images for illustrated stills, blender for 3D scenes. Chosen for you when omitted.

Available options:
motif,
images,
blender
ttsProvider
string

Narration engine. Left to the deployment default when omitted.

Required string length: 1 - 60
ttsVoice
string

A voice id understood by ttsProvider.

Required string length: 1 - 200
ttsModel
string

A model id understood by ttsProvider.

Required string length: 1 - 200
callbackUrl
string<uri>

An https URL to POST the finished job to, signed with X-VC-Signature. Omit it and poll GET /v1/jobs/{jobId} instead.

projectId
string

The project to file this work under. Optional: omit it and one is created for you, and its id comes back on the response — read it from there rather than assuming. Pass the same id across calls when you want the script, the render and the thumbnail to land in one container. A project this workspace does not own answers not_found; the work is never silently filed somewhere else.

Required string length: 1 - 200

Response

Success.

success
boolean
required
projectId
string
required

The project this work was filed under. Read it from here — a call that sent no projectId had one created, and this is where its id comes back.

Example:

"prj_9x2a4c"

credits
number
required

What this call actually cost, which is not always what was quoted.

Example:

300

jobId
string
required

Poll GET /v1/jobs/{jobId}. When that job reports status: "done", the finished file is job.artifacts.video — an origin URL you fetch directly, not through this API.

Example:

"job_4k1b7d"

status
string
required

Acceptance, not completion. The work has not started when this returns.

Allowed value: "queued"
creditBalance
number

Your balance after the charge. Absent when billing is disabled for the workspace.

Example:

3900

{key}
any