Skip to content

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.

  1. Open API (in the menu under the round button with your initial, top right).
  2. Under Keys, type a name for the key and click Create key.
  3. 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.

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.

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}/cancel cancels 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.

  • 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 its stage says 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 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.needed webhook to the video’s webhook_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.

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 a 409: send it again a moment later.

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.

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.

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.

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.

  • GET /api/v1/account: your minutes left (null for 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/languages and GET /api/v1/music: what voice, language and music take. A voice comes with its id (what voice takes, not its name), its name, 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.

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