Other ways to make videos
Make videos with the API
The API makes videos the way the New video page does, from your own code: send the page to start on and what the video should teach, and SayScreen records, narrates and edits it. Each video uses your account’s minutes, like one made in the app, and shows up with your other videos.
Get a key
Section titled “Get a key”- Open API (in the menu under the round button with your initial, top right).
- Under Keys, type a name for the key and click Create key.
- Copy the key. It’s shown once.
Send it with every call, in the Authorization header:
Authorization: Bearer ss_your_key
Keep it secret: anyone with it can make videos with your minutes. To stop a key working, delete it on the API page.
Make a video
Section titled “Make a video”Send a POST to https://app.sayscreen.com/api/v1/videos:
curl https://app.sayscreen.com/api/v1/videos \
-H "Authorization: Bearer $SAYSCREEN_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://app.yourproduct.com/projects", "prompt": "Show how to create a project and invite a teammate."}'
The answer is the video, with its id and status queued. What you can send:
| Field | What it is |
|---|---|
url |
The page the video starts on. Required. https:// is added if you leave it out. |
prompt |
What the video should teach, as you’d write it on the New video page: 8 to 8,000 characters. Required. See Write a prompt that gets the video you want. |
title |
The video’s title. Without one, SayScreen writes it. |
voice |
A voice’s id from GET /api/v1/voices, or "random". |
speed |
How fast the narrator speaks, from 0.7 to 1.2. |
language |
A language’s code from GET /api/v1/languages, such as "es". |
ratio |
"16:9" or "9:16". |
music |
"none", "random", or a track’s id from GET /api/v1/music. |
captions |
Captions burned into the video: false for none, true for your usual look, or a look: "dark", "light", "outline" or "highlight". |
max_minutes |
The longest the video may run, from 1 to 8 (5 on a trial). Leave it out for the most your account allows. |
project |
The name of a project to put the video in. It’s made if you have none by that name. |
webhook_url |
An https address to tell when the video is done (see Webhooks below). |
metadata |
A JSON object of your own, up to 2,000 characters, given back with the video. |
Anything you leave out comes from your New video page: the voice, language, look, music and ratio your last new video was made with. Each video says what it was made with (voice, speed, language, ratio, captions, music and max_minutes), so you can check.
To try a call without writing code, any API testing tool works, including the ones that run in a browser tab.
Make many at once
Section titled “Make many at once”Send a POST to https://app.sayscreen.com/api/v1/batches with up to 500 videos in videos, each with the fields above. Put the fields they share in defaults, and project puts them all in one project:
{
"project": "Grade 3 Math",
"defaults": { "max_minutes": 6, "webhook_url": "https://example.com/sayscreen" },
"videos": [
{ "url": "https://lms.example.com/lesson/1", "prompt": "Walk through lesson 1 and its practice questions.", "metadata": { "lesson": 1 } },
{ "url": "https://lms.example.com/lesson/2", "prompt": "Walk through lesson 2 and its practice questions.", "metadata": { "lesson": 2 } }
]
}
Every video is checked before any is made: if one has a mistake, none is made, and the error says which, such as videos[3].url. The answer has the batch’s id and its videos.
GET /api/v1/batches/{id}counts the batch’s videos by status and lists them.POST /api/v1/batches/{id}/cancelcancels those still waiting or being made. Videos already made stay.
Up to 5,000 of your videos can wait their turn at once. Send more as those are made.
How your videos are made
Section titled “How your videos are made”- One at a time, in the order they came. A video you make in the app goes before the next one from the API.
- A video starts once your account has the minutes for all of it (its
max_minutes), so none is cut short. Until then it waits, and itsstagesays so. Buy more minutes on the Billing page and it goes on by itself. - Each one uses minutes for its length once it’s made, as in the app. A cancelled video uses none.
- Pages behind a sign-in: sign in to the site once in SayScreen first (Settings, Sign in to a site ahead of time). See the next section for when a sign-in runs out.
- They show in the app with your other videos, where you can change the words, the look or anything else.
When a site needs a sign-in
Section titled “When a site needs a sign-in”When a video comes to a sign-in SayScreen doesn’t have (one that was never made, or one that ran out), that site’s videos wait instead of failing. Your videos for other sites carry on.
- You hear once, not once a video: a
sign_in.neededwebhook to the video’swebhook_url, and an email to your account. Both have a link that opens SayScreen’s sign-in for the site. - Sign in there, and the waiting videos carry on by themselves, in their order.
- If a video still comes to a sign-in after you’ve signed in, that one fails with the reason, as the page needs something the sign-in didn’t give.
- When you send videos for a site with no recent sign-in, SayScreen looks at the site first, so you hear about a missing sign-in before any of them starts.
GET /api/v1/account lists the sites waiting in waiting_for_sign_in, each with its sign_in_url and how many videos wait on it.
Retry safely
Section titled “Retry safely”A call can time out after SayScreen got it. To send it again without making the video twice, give each POST an Idempotency-Key header: any value of your own, up to 255 characters with no spaces, such as a UUID or your lesson’s id.
curl https://app.sayscreen.com/api/v1/videos \
-H "Authorization: Bearer $SAYSCREEN_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: lesson-42" \
-d '{"url": "https://lms.example.com/lesson/42", "prompt": "Walk through lesson 42."}'
- The same call with the same key within 24 hours gets the first answer again, with the header
Idempotent-Replayed: true, and nothing new is made. - Only a call that worked is remembered: if the first one failed, sending it again tries again.
- The same key with a different call is a
422. While the first call is still being made, a repeat is a409: send it again a moment later.
See your calls and webhooks
Section titled “See your calls and webhooks”The API page keeps the last 30 days:
- Calls lists every call made with your keys: when, what was called, its status and which key. Click one to see what was sent and what came back. Failed shows only the calls that didn’t work.
- Webhooks lists every webhook with each try and what your server answered. Resend sends one again at once, with the video as it is now.
Check on a video
Section titled “Check on a video”GET /api/v1/videos/{id} gives the video:
{
"id": "20261114-0930-1a2b3c",
"status": "done",
"stage": null,
"progress": null,
"error": null,
"title": "Create a project and invite a teammate",
"url": "https://app.yourproduct.com/projects",
"prompt": "Show how to create a project and invite a teammate.",
"language": "en",
"voice": { "id": "AaOhDHYJ1XLZk74lXhdE", "name": "Caleb" },
"ratio": "16:9",
"duration": 94.2,
"project": "Grade 3 Math",
"batch": "b_x8K2mQ0aZp4",
"metadata": { "lesson": 1 },
"source": "api",
"created_at": "2026-11-14T09:30:12.000Z",
"finished_at": "2026-11-14T09:41:55.000Z",
"app_url": "https://app.sayscreen.com/p/20261114-0930-1a2b3c",
"files": {
"video": "https://app.sayscreen.com/api/v1/videos/20261114-0930-1a2b3c/video.mp4",
"captions": "https://app.sayscreen.com/api/v1/videos/20261114-0930-1a2b3c/captions.srt",
"thumbnail": "https://app.sayscreen.com/api/v1/videos/20261114-0930-1a2b3c/thumbnail.jpg"
},
"youtube": { "titles": ["..."], "description": "..." }
}
status is queued, making, done, failed or cancelled. While it’s waiting or being made, stage says what’s happening, and progress goes from 0 to 1 within each stage that has one, such as the voiceover and the edit. finished_at is set once it’s done. When it failed, error says why.
GET /api/v1/videos lists your videos, newest first, 20 at a time (limit takes up to 100). Filter with status, batch, project (its name), or source=api. For the next page, add starting_after with the last video’s id, while has_more is true.
Download it
Section titled “Download it”Once status is done, files has the video (MP4), its captions (.srt) and its thumbnail. Download them with your key, like any other call:
curl -L -H "Authorization: Bearer $SAYSCREEN_KEY" -o lesson-1.mp4 https://app.sayscreen.com/api/v1/videos/20261114-0930-1a2b3c/video.mp4
youtube has the video’s title options and description, ready for YouTube.
Webhooks
Section titled “Webhooks”Send webhook_url with a video and SayScreen sends a POST there when it’s done, has failed or was cancelled. The body is JSON: type (video.done, video.failed or video.cancelled), created (the time, in seconds) and data (the video, as above). A sign_in.needed one comes when the video’s site needs a sign-in: its data has site, sign_in_url, waiting and video. Answer with any 2xx status. If your server doesn’t, it’s sent again later, for several hours. Each try shows under Webhooks on the API page, where Resend sends it again, and you can always look the video up instead.
To check a webhook is from SayScreen, use your Webhook signing secret (on the API page, under Keys). The SayScreen-Signature header is t=<time>,v1=<signature>, where the signature is the HMAC-SHA256, in hex, of the time, a dot and the body exactly as it arrived, keyed with your secret. In Node:
const crypto = require('crypto');
function isFromSayScreen(header, rawBody, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && parts.v1?.length === expected.length && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}
Replace gives you a new secret. Webhooks are signed with the new one from then on.
Other calls
Section titled “Other calls”GET /api/v1/account: your minutes left (nullfor an account whose minutes aren’t counted), how many videos are waiting, and any sites waiting for a sign-in.GET /api/v1/voices,GET /api/v1/languagesandGET /api/v1/music: whatvoice,languageandmusictake. A voice comes with itsid(whatvoicetakes, not its name), itsname, whether it’s one of the best (best) or your own (yours), and the languages it speaks.POST /api/v1/videos/{id}/cancel: stops a video that’s waiting or being made. It uses no minutes.DELETE /api/v1/videos/{id}: deletes a video for good.
Errors
Section titled “Errors”An error comes with an HTTP status and a body like { "error": { "code": "invalid_request", "message": "url is missing: the page the video starts on.", "param": "url" } }. The message says what to do.
| Status | What it means |
|---|---|
400 |
Something in the request is wrong. param says which field. |
415 |
The body wasn’t sent as JSON: add the header Content-Type: application/json. |
401 |
The key is missing, or isn’t one of yours (it may have been deleted). |
402 |
Your account can’t make videos right now, as when its plan has ended. |
404 |
There’s no such video or batch in your account. |
409 |
Not now, such as deleting a video that’s being made, or a repeat of a call with the same Idempotency-Key that’s still being made. |
422 |
The Idempotency-Key was used with a different call. Use a new key for a new call. |
429 |
Too many calls in a short time, or too many videos waiting. Wait a minute and try again. |
Still stuck? Email hey@sayscreen.com and a person will answer.
Email us© 2026 SayScreen