From a document to a video

Send your text to POST /v1/video/render and Sigmora writes the narration plan, records the voice-over, makes the visuals and renders the file. The call returns a job id straight away; poll the job and download the video when it is done. You do not upload the text or look up an id first. You only need a project to file the video in.

Render a video

curl -X POST https://api.sigmora.org/v1/video/render \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: week5-stats-render-001" \
  -d '{
    "projectId": "prj_9x2a4c",
    "story": "Statistics is the science of collecting, organising, analysing and interpreting data. Two branches cover almost everything. Descriptive statistics summarise what a dataset shows...",
    "title": "Statistics for AI — Week 5",
    "videoType": "lesson",
    "aspect": "horizontal",
    "quality": "h"
  }'

import os
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['SIGMORA_API_KEY']}"

render = session.post(
    "https://api.sigmora.org/v1/video/render",
    headers={"Idempotency-Key": "week5-stats-render-001"},
    json={
        "projectId": "prj_9x2a4c",
        "story": "Statistics is the science of collecting, organising, analysing and interpreting data...",
        "title": "Statistics for AI — Week 5",
        "videoType": "lesson",
        "aspect": "horizontal",
        "quality": "h",
    },
    timeout=60,
).json()
print(render["jobId"], render["videoType"])

const headers = {
  Authorization: `Bearer ${process.env.SIGMORA_API_KEY}`,
  "Content-Type": "application/json",
};

const render = await fetch("https://api.sigmora.org/v1/video/render", {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "week5-stats-render-001" },
  body: JSON.stringify({
    projectId: "prj_9x2a4c",
    story: "Statistics is the science of collecting, organising, analysing and interpreting data...",
    title: "Statistics for AI — Week 5",
    videoType: "lesson",
    aspect: "horizontal",
    quality: "h",
  }),
}).then((r) => r.json());
console.log(render.jobId, render.videoType);

Response

{
  "success": true,
  "projectId": "prj_9x2a4c",
  "jobId": "job_4k1b7d",
  "status": "queued",
  "videoType": "lesson",
  "courseWorkflowId": "general_course",
  "courseWorkflowVersion": "1",
  "credits": 300,
  "creditBalance": 3900
}

status: "queued" means the render was accepted, not that it is finished.

Parameters

projectId and story are the only fields you need. story takes up to 40,000 characters — a long lecture fits.

Field	Description
`projectId`	Required. The project to file the video in. Create it with `POST /v1/projects`.
`story`	Required for this flow. Your text, narrated and rendered.
`videoType`	How the text is filmed: `lesson`, `howto`, `story` or `social`. Chosen from your writing when omitted — except `social`, which you must ask for.
`title`	The video’s title. Derived from the text when omitted.
`aspect`	`horizontal` for long-form (the default) or `vertical` for feeds.
`quality`	`l`, `m`, `h` or `k` (4K). The price is the same; higher quality takes longer.
`renderer`	`motif` for animated typography and diagrams, `images` for illustrated stills, `blender` for 3D scenes. Chosen for you when omitted.
`ttsProvider`, `ttsVoice`, `ttsModel`	A specific narration provider, voice and model. Omit all three for the default voice.
`targetMinutes`	A runtime target for a lesson. It guides the writing and never cuts your source.
`package`	`{"shorts": N}` plans `N` short-form scripts per platform on the same job. `0`, the default, means none.
`draft`	`true` renders a low-cost 480p review copy. Finalize it with `POST /v1/jobs/{jobId}/finalize`.
`callbackUrl`, `callbackSecret`	A signed webhook when the job finishes. Send both or neither. See Webhooks.

Lessons can also take courseWorkflowId with courseWorkflowVersion, courseCapabilities, courseVideoArchetype and courseVideoTemplateId to pick a specific teaching workflow and visual template. Omit them to use the default lesson workflow, general_course version 1; the response reports which one ran. GET /v1/video/options lists every installed workflow, template, voice and renderer.

Choose how it is filmed

videoType picks a different production, not a different style on one template:

`videoType`	What it makes	Use it for
`lesson`	Explains a subject: definitions, worked steps, the shape of a class	Notes, articles, documentation — anything expository
`howto`	Numbered, narrated steps with the actions on screen	Instructions, runbooks, setup guides
`story`	Narrative with a cold open and a build	Something that happened to someone
`social`	Vertical short-form: a hook in the first half-second, escalating beats, large on-screen text that works with the sound off	TikTok, Reels and Shorts

When you omit videoType, Sigmora reads your writing: imperatives and numbered steps become a how-to, definitions and derivations a lesson, past-tense action a story. It never picks social on its own, because the same paragraph can be a lesson or a short depending on where you will post it. The response always says which type was used — if it is not what you wanted, set it explicitly next time.

The wrong type shows in the finished video. The story pipeline opens cold and paces beats for drama, so a lecture rendered as a story plays like one.

To render an entry from Sigmora’s video catalogue instead of your own text, send domain and videoId rather than story. List the domains with GET /v1/video/catalog/domains and find ids with GET /v1/video/catalog/{domain}. Sending domain together with story is refused.

Collect the video

Rendering takes minutes. Poll the job every 15–30 seconds:

curl https://api.sigmora.org/v1/jobs/job_4k1b7d \
  -H "Authorization: Bearer $SIGMORA_API_KEY"

import random
import time

while True:
    job = session.get("https://api.sigmora.org/v1/jobs/job_4k1b7d", timeout=30).json()["job"]
    if job["status"] in {"done", "cancelled", "failed", "qa_failed"}:
        break
    time.sleep(15 + random.random() * 5)

if job["status"] == "done":
    print(job["artifacts"]["download"])
else:
    print("Render ended as", job["status"], job.get("error"))

let job;
while (true) {
  ({ job } = await fetch("https://api.sigmora.org/v1/jobs/job_4k1b7d", { headers }).then((r) => r.json()));
  if (["done", "cancelled", "failed", "qa_failed"].includes(job.status)) break;
  await new Promise((resolve) => setTimeout(resolve, 15_000 + Math.random() * 5_000));
}

if (job.status === "done") console.log(job.artifacts.download);
else console.log("Render ended as", job.status, job.error);

While it works:

{ "success": true, "job": { "id": "job_4k1b7d", "kind": "video.render", "status": "rendering", "phase": "narrating" } }

When it is done:

{
  "success": true,
  "job": {
    "id": "job_4k1b7d",
    "kind": "video.render",
    "status": "done",
    "artifacts": {
      "download": "https://api.sigmora.org/render/job_4k1b7d/download/video?exp=1785700000&sig=9f2c",
      "playback": "https://api.sigmora.org/public/job_4k1b7d/master.m3u8",
      "thumbnail": "https://api.sigmora.org/render/job_4k1b7d/download/thumbnail?exp=1785700000&sig=1b7e",
      "srt": "https://api.sigmora.org/render/job_4k1b7d/download/srt?exp=1785700000&sig=c41a",
      "vtt": "https://api.sigmora.org/render/job_4k1b7d/download/vtt?exp=1785700000&sig=77d0"
    }
  }
}

job.artifacts.download is your video file. It is a signed link: fetch it without an Authorization header, or hand it to a browser, a downloader or a <video> tag. Captions come with it as SubRip (srt) and WebVTT (vtt).

Signed links expire. Download promptly and poll the job again for fresh links rather than storing them. A null field means that artifact was not produced.

Branch on status, not phase: phase is a progress label that changes as the pipeline evolves. A qa_failed render is blocked from release — read artifacts.scriptReview to see why, and do not publish it. See Jobs & polling for every status.

Get the posting package

Most videos are made to be posted, so the extras come with the render:

The posting block — title, timestamped chapters, tags and full transcript — comes with every render at no extra cost: job.artifacts.youtube as text to paste, and job.artifacts.metadata as JSON to publish programmatically.
Shorts, when you ask for them with package:

curl -X POST https://api.sigmora.org/v1/video/render \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: week5-stats-package-001" \
  -d '{
    "projectId": "prj_9x2a4c",
    "story": "Statistics is the science of collecting, organising, analysing and interpreting data...",
    "videoType": "lesson",
    "package": { "shorts": 2, "platforms": ["tiktok", "shorts"] }
  }'

render = session.post(
    "https://api.sigmora.org/v1/video/render",
    headers={"Idempotency-Key": "week5-stats-package-001"},
    json={
        "projectId": "prj_9x2a4c",
        "story": "Statistics is the science of collecting, organising, analysing and interpreting data...",
        "videoType": "lesson",
        "package": {"shorts": 2, "platforms": ["tiktok", "shorts"]},
    },
    timeout=60,
).json()

const packaged = await fetch("https://api.sigmora.org/v1/video/render", {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "week5-stats-package-001" },
  body: JSON.stringify({
    projectId: "prj_9x2a4c",
    story: "Statistics is the science of collecting, organising, analysing and interpreting data...",
    videoType: "lesson",
    package: { shorts: 2, platforms: ["tiktok", "shorts"] },
  }),
}).then((r) => r.json());

The shorts appear on the same job under job.package once the video is done:

{ "package": { "status": "ready", "shorts": 2, "clips": [ … ] } }

package.status is pending until the video finishes, then ready. With shorts: 0 it is skipped.

Shorts are scripts, not video files. Each one names its platform, target length, the part of your video it comes from and why, plus the script. Shorts are charged when they are planned, after the video finishes — a render that never finishes never bills for them.

Plan shorts later

To decide after you have seen the video, plan shorts from the finished job with POST /v1/video/shorts:

curl -X POST https://api.sigmora.org/v1/video/shorts \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: week5-stats-shorts-001" \
  -d '{
    "projectId": "prj_9x2a4c",
    "jobId": "job_4k1b7d",
    "platforms": ["tiktok", "shorts", "reels"],
    "maxPerPlatform": 3
  }'

Retry without paying twice

Keep the Idempotency-Key with your record of the render. If the request times out, send the same body with the same key: you get the original response back instead of a second render and a second charge. A render that fails after it was accepted is refunded.

If the document is not written yet

POST /v1/video/render narrates text you already have. To start from a topic, write it first with a text capability — text.research for a brief, text.paraphrase to restyle something long, or text.script to build on a seed video — then render the result.

Video, footage & 3D

Edit your own footage, render 3D, and discover every video option.

Jobs & polling

Every job status, artifact and how to cancel.

Get started

Create

Grow & automate

Integrate

Build reliably

Operate

From a document to a video

Render a video

Parameters

Choose how it is filmed

Collect the video

Get the posting package

Plan shorts later

Retry without paying twice

If the document is not written yet

Video, footage & 3D

Jobs & polling

​Render a video

​Parameters

​Choose how it is filmed

​Collect the video

​Get the posting package

​Plan shorts later

​Retry without paying twice

​If the document is not written yet

Video, footage & 3D

Jobs & polling

Render a video

Parameters

Choose how it is filmed

Collect the video

Get the posting package

Plan shorts later

Retry without paying twice

If the document is not written yet