Video, footage & 3D

All video work follows the same pattern: send a request with a projectId and an Idempotency-Key, receive a jobId, and poll GET /v1/jobs/{jobId} until it is done. See Jobs & polling.

Choose an operation

You want to	Call	Returns
Turn writing into a narrated video	`POST /v1/video/render`	`jobId` — see From a document to a video
Edit your own footage into a cut and shorts	`POST /v1/video/edit`	`parentJobId` and `childJobIds`
Approve the cuts of a reviewed edit	`POST /v1/video/edit/approve`	Render job ids
Plan short-form scripts from a finished render	`POST /v1/video/shorts`	The planned clips
Find the moments worth cutting in a transcript	`POST /v1/video/moments`	Scored moments — see Text
Make a creator-style UGC video	`POST /v1/video/ugc`	`jobId`
Generate an animated 3D object from text	`POST /v1/3d/from-text`	`jobId`
Generate an animated 3D object from a photo	`POST /v1/3d/from-image`	`jobId`
Discover voices, templates, renderers and formats	`GET /v1/video/options`	The live option registry
Find catalogue video ids	`GET /v1/video/catalog/{domain}`	Paged `videoId` values
Verify a file’s provenance record	`POST /v1/video/provenance/verify`	A verdict — see Provenance

Discover video options

GET /v1/video/options returns everything POST /v1/video/render and the 3D operations accept right now: narration providers, models and voices; lesson workflows, teaching capabilities and templates; chess formats and audiences; renderer readiness; short-form platforms; and artifact kinds. Read it instead of hard-coding these values. It is free.

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

Edit your own footage

Give Sigmora your raw clips and a brief, and it produces an edited long-form cut and, if you ask, short-form clips — removing false starts, tightening pacing and packaging the result.

Add the footage to the project

Import each clip from a public HTTPS URL with POST /v1/assets/import, or upload files from disk with the upload operations (POST /v1/assets/upload/prepare, then POST /v1/assets/upload/complete). Each returns an asset; its contentId is the clip id the editor takes.

curl -X POST https://api.sigmora.org/v1/assets/import \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kitchen-ep12-clip-a" \
  -d '{
    "projectId": "prj_9x2a4c",
    "sourceUrl": "https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
    "title": "Kitchen episode 12 — take A"
  }'

import os
import requests

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

asset = session.post(
    "https://api.sigmora.org/v1/assets/import",
    headers={"Idempotency-Key": "kitchen-ep12-clip-a"},
    json={
        "projectId": "prj_9x2a4c",
        "sourceUrl": "https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
        "title": "Kitchen episode 12 — take A",
    },
    timeout=120,
).json()["asset"]
print(asset["contentId"], asset["status"])

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

const { asset } = await fetch("https://api.sigmora.org/v1/assets/import", {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "kitchen-ep12-clip-a" },
  body: JSON.stringify({
    projectId: "prj_9x2a4c",
    sourceUrl: "https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
    title: "Kitchen episode 12 — take A",
  }),
}).then((r) => r.json());
console.log(asset.contentId, asset.status);

Before editing, poll GET /v1/assets/{assetId}/ingest?projectId=... until ready is true; its contentId is the value to pass in clipIds.

Submit the edit

shootId is any stable id you choose to group the clips of one shoot. clipIds are the assets’ contentId values. Set shortsCount for short-form outputs, and reviewCuts: true to approve the cuts before anything renders.

curl -X POST https://api.sigmora.org/v1/video/edit \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kitchen-ep12-edit-001" \
  -d '{
    "projectId": "prj_9x2a4c",
    "shootId": "shoot-2026-10-04-kitchen",
    "clipIds": ["cnt_a1f4e2", "cnt_b7c903"],
    "title": "Kitchen budget tips — episode 12",
    "brief": "Keep the energy up, cut the false starts, and lead with the receipt reveal.",
    "shortsCount": 2,
    "reviewCuts": true
  }'

edit = session.post(
    "https://api.sigmora.org/v1/video/edit",
    headers={"Idempotency-Key": "kitchen-ep12-edit-001"},
    json={
        "projectId": "prj_9x2a4c",
        "shootId": "shoot-2026-10-04-kitchen",
        "clipIds": ["cnt_a1f4e2", "cnt_b7c903"],
        "title": "Kitchen budget tips — episode 12",
        "brief": "Keep the energy up, cut the false starts, and lead with the receipt reveal.",
        "shortsCount": 2,
        "reviewCuts": True,
    },
    timeout=120,
).json()
print(edit["parentJobId"], edit["childJobIds"])

const edit = await fetch("https://api.sigmora.org/v1/video/edit", {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "kitchen-ep12-edit-001" },
  body: JSON.stringify({
    projectId: "prj_9x2a4c",
    shootId: "shoot-2026-10-04-kitchen",
    clipIds: ["cnt_a1f4e2", "cnt_b7c903"],
    title: "Kitchen budget tips — episode 12",
    brief: "Keep the energy up, cut the false starts, and lead with the receipt reveal.",
    shortsCount: 2,
    reviewCuts: true,
  }),
}).then((r) => r.json());
console.log(edit.parentJobId, edit.childJobIds);

Footage edits are priced per output, the long cut and each short. A source longer than 20 minutes adds one more unit per started 20 minutes beyond the first (45 minutes adds 2). The quote (x-sigmora-quote-only) includes it.

Collect the outputs

Poll the job ids with GET /v1/jobs/{jobId}. Without reviewCuts, the edit renders straight through to done. With it, the parent job stops at awaiting_review — continue below.

Review the cuts before rendering

A review-mode edit stops at awaiting_review with a proposal: the cuts it wants to make, the topics it found, and the moments that would stand alone as shorts. Nothing renders until the cut is approved.

Page through the proposal with GET /v1/jobs/{jobId}/proposal, using after and page.nextAfter (see Pagination).
Approve the cuts you want with POST /v1/video/edit/approve. You can also drop whole topics, or pick specific topics and moments to cut as shorts.

curl "https://api.sigmora.org/v1/jobs/job_7e3c2f/proposal?limit=50" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"

curl -X POST https://api.sigmora.org/v1/video/edit/approve \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kitchen-ep12-approve-001" \
  -d '{
    "projectId": "prj_9x2a4c",
    "parentJobId": "job_7e3c2f",
    "appliedCutIds": ["cut_01", "cut_03", "cut_07"],
    "shortMomentIds": ["moment_02"]
  }'

proposal = session.get(
    "https://api.sigmora.org/v1/jobs/job_7e3c2f/proposal", params={"limit": 50}, timeout=30
).json()

approved = session.post(
    "https://api.sigmora.org/v1/video/edit/approve",
    headers={"Idempotency-Key": "kitchen-ep12-approve-001"},
    json={
        "projectId": "prj_9x2a4c",
        "parentJobId": "job_7e3c2f",
        "appliedCutIds": [cut["id"] for cut in proposal["cuts"]],
        "shortMomentIds": [proposal["moments"][0]["id"]],
    },
    timeout=60,
).json()
print(approved["childJobIds"])

const proposal = await fetch("https://api.sigmora.org/v1/jobs/job_7e3c2f/proposal?limit=50", { headers }).then((r) =>
  r.json(),
);

const approved = await fetch("https://api.sigmora.org/v1/video/edit/approve", {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "kitchen-ep12-approve-001" },
  body: JSON.stringify({
    projectId: "prj_9x2a4c",
    parentJobId: "job_7e3c2f",
    appliedCutIds: proposal.cuts.map((cut: { id: string }) => cut.id),
    shortMomentIds: [proposal.moments[0].id],
  }),
}).then((r) => r.json());
console.log(approved.childJobIds);

appliedCutIds takes only ids from the stored proposal; an empty list keeps all the footage. The approval starts the renders and returns their job ids to poll.

Generate 3D

Describe an object, or send a photo of one, and receive an animated 3D render. Both operations are asynchronous and need GPU capacity — check available in GET /v1/capabilities first; when they cannot run, the call is refused with 503 capability_unavailable before you are charged.

curl -X POST https://api.sigmora.org/v1/3d/from-text \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ceramic-mug-3d-001" \
  -d '{
    "projectId": "prj_9x2a4c",
    "prompt": "A matte terracotta coffee mug with a thin gold rim and a curved handle",
    "preset": "turntable",
    "durationSeconds": 6,
    "background": "studio"
  }'

job = session.post(
    "https://api.sigmora.org/v1/3d/from-text",
    headers={"Idempotency-Key": "ceramic-mug-3d-001"},
    json={
        "projectId": "prj_9x2a4c",
        "prompt": "A matte terracotta coffee mug with a thin gold rim and a curved handle",
        "preset": "turntable",
        "durationSeconds": 6,
        "background": "studio",
    },
    timeout=60,
).json()
print(job["jobId"])

const job = await fetch("https://api.sigmora.org/v1/3d/from-text", {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "ceramic-mug-3d-001" },
  body: JSON.stringify({
    projectId: "prj_9x2a4c",
    prompt: "A matte terracotta coffee mug with a thin gold rim and a curved handle",
    preset: "turntable",
    durationSeconds: 6,
    background: "studio",
  }),
}).then((r) => r.json());
console.log(job.jobId);

POST /v1/3d/from-image takes assetUrl — a public or signed URL of the photo — instead of prompt. Presets are turntable, orbit, dolly_in, float_bob and beauty. When the job is done, download the result from artifacts.download with your API key, following the redirect (see Jobs & polling).

Draft renders

Set draft: true on POST /v1/video/render for a low-cost 480p review copy. When you are happy, finalize it with POST /v1/jobs/{jobId}/finalize and the draft’s projectId: the same video renders at full quality as a new job, and reuses the draft’s script and narration. Each accepted render is charged; the same Idempotency-Key returns the same final job and is never charged twice. A job that is not a draft answers 409 conflict.

curl -X POST https://api.sigmora.org/v1/jobs/job_4k1b7d/finalize \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Idempotency-Key: finalize-job_4k1b7d-1" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "prj_9x2a4c"}'

offlineSlots: true fills visuals without external image providers, for fully deterministic output. It cannot be combined with renderer: "blender".

Release checks

Before narration, each render’s script is reviewed against its source for accuracy, fidelity, audience fit and pacing. If the review blocks the script, the job ends as qa_failed before any narration or render cost — read job.artifacts.scriptReview to see the evidence, fix the input, and submit again rather than retrying unchanged.

Retries and ownership

Send a stable Idempotency-Key with every POST, and reuse it only with the same body.
Accepted async work may answer 200 or 202. Branch on the body — the jobId and status — not on that difference.
A job from another workspace answers 404 not_found.
A temporary outage reading a job answers 503 upstream_unavailable; retry. It is never reported as a missing job.

Chess videos

Render a full analysis of a Lichess game.

Content intelligence

Analyze a reference video and turn it into a production brief.

Get started

Create

Grow & automate

Integrate

Build reliably

Operate

Choose an operation

Discover video options

Edit your own footage

Review the cuts before rendering

Generate 3D

Draft renders

Release checks

Retries and ownership

More video workflows

Chess videos

Content intelligence

​Choose an operation

​Discover video options

​Edit your own footage

​Review the cuts before rendering

​Generate 3D

​Draft renders

​Release checks

​Retries and ownership

​More video workflows

Chess videos

Content intelligence

Choose an operation

Discover video options

Edit your own footage

Review the cuts before rendering

Generate 3D

Draft renders

Release checks

Retries and ownership

More video workflows