Quickstart

In a few minutes you will read the live capability catalogue, create a project, and run text.script — a capability that watches a video, researches the topic, fact-checks its claims and returns a finished script.

Prerequisites

A Sigmora workspace. Sign up if you do not have one.
An API key for that workspace, created in the dashboard under Settings → API keys.
For the Python examples, requests (pip install requests). The TypeScript examples use the built-in fetch in Node.js 18 or later.

Make your first calls

Set your API key

Export your key as an environment variable. Every example in these docs reads it from SIGMORA_API_KEY.

export SIGMORA_API_KEY="sk_live_..."

A key is shown once, when you create it. If you cannot open Settings → API keys, ask a workspace owner to create one for you.

See what you can call, and what it costs

GET /v1/capabilities returns every capability with its current price in credits, whether it can run right now, and your credit balance. Reading it is free.

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

import os
import requests

BASE_URL = "https://api.sigmora.org"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['SIGMORA_API_KEY']}"

catalogue = session.get(f"{BASE_URL}/v1/capabilities", timeout=30).json()
for capability in catalogue["capabilities"]:
    print(capability["id"], capability["credits"], capability["available"])
print("Balance:", catalogue["creditBalance"])

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

const catalogue = await fetch(`${BASE_URL}/v1/capabilities`, { headers }).then((r) => r.json());
for (const capability of catalogue.capabilities) {
  console.log(capability.id, capability.credits, capability.available);
}
console.log("Balance:", catalogue.creditBalance);

Response

{
  "success": true,
  "capabilities": [
    { "id": "text.script", "method": "POST", "path": "/v1/text/script", "credits": 150, "available": true },
    { "id": "video.render", "method": "POST", "path": "/v1/video/render", "credits": 300, "available": true, "async": true }
  ],
  "creditBalance": 4200,
  "billingEnabled": true,
  "workspaceId": "ws_91c2"
}

Create a project

Every capability files its output in a project, so create one first. Creating a project is free. mediaType is video or audio; a video project also names the production path that fits the work (general fits anything).

curl -X POST https://api.sigmora.org/v1/projects \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-project-0001" \
  -d '{
    "title": "Open film explainer",
    "mediaType": "video",
    "videoPath": "general"
  }'

project = session.post(
    f"{BASE_URL}/v1/projects",
    headers={"Idempotency-Key": "quickstart-project-0001"},
    json={"title": "Open film explainer", "mediaType": "video", "videoPath": "general"},
    timeout=30,
).json()["project"]
print(project["id"])

const { project } = await fetch(`${BASE_URL}/v1/projects`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "quickstart-project-0001" },
  body: JSON.stringify({ title: "Open film explainer", mediaType: "video", videoPath: "general" }),
}).then((r) => r.json());
console.log(project.id);

Response

{
  "success": true,
  "project": {
    "id": "prj_9x2a4c",
    "title": "Open film explainer",
    "kind": "video",
    "mediaType": "video",
    "videoPath": "general",
    "status": "active",
    "visibility": "private"
  }
}

Idempotency-Key is required here. If the request times out, send it again with the same key and you get the same project back instead of a second one.

Run a capability

Send a seed video and an angle to POST /v1/text/script. Pass the project id from the previous step as projectId. The call is synchronous and can take a few minutes, so use a generous client timeout.

curl -X POST https://api.sigmora.org/v1/text/script \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-script-0001" \
  --max-time 600 \
  -d '{
    "projectId": "prj_9x2a4c",
    "sourceUrl": "https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
    "angle": "how open animated films are produced",
    "targetDurationMinutes": 8
  }'

result = session.post(
    f"{BASE_URL}/v1/text/script",
    headers={"Idempotency-Key": "quickstart-script-0001"},
    json={
        "projectId": project["id"],
        "sourceUrl": "https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
        "angle": "how open animated films are produced",
        "targetDurationMinutes": 8,
    },
    timeout=600,
).json()
print(result["credits"], "credits charged")
print(result["script"])

const result = await fetch(`${BASE_URL}/v1/text/script`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "quickstart-script-0001" },
  body: JSON.stringify({
    projectId: project.id,
    sourceUrl: "https://storage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4",
    angle: "how open animated films are produced",
    targetDurationMinutes: 8,
  }),
  signal: AbortSignal.timeout(600_000),
}).then((r) => r.json());
console.log(result.credits, "credits charged");
console.log(result.script);

Response

{
  "success": true,
  "projectId": "prj_9x2a4c",
  "script": { "title_options": ["..."], "script": "...", "research": { "claims_checked": ["..."] } },
  "credits": 150,
  "creditBalance": 4050
}

credits is what was actually charged and creditBalance is what is left. A call that fails before producing a usable result is free.

Read the project back

Pass the same projectId to every related call and the script, renders and thumbnails collect in one place you can read with one request.

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

print(session.get(f"{BASE_URL}/v1/projects/{project['id']}", timeout=30).json())

console.log(await fetch(`${BASE_URL}/v1/projects/${project.id}`, { headers }).then((r) => r.json()));

Long-running work returns a job

Rendering video takes minutes, so POST /v1/video/render, POST /v1/video/edit and the 3D capabilities answer immediately with a jobId. Poll GET /v1/jobs/{jobId} until status is terminal:

`status`	Meaning
`queued`, `rendering`	Still working. Poll again in 15–30 seconds.
`done`	Finished. The file is at `job.artifacts.download`.
`failed`, `cancelled`, `qa_failed`	Finished without a releasable file. Any charge is refunded.
`awaiting_review`	Waiting for a person to approve a footage edit. Polling will not move it.

Jobs & polling covers every status and artifact, and From a document to a video walks a render end to end.

Next steps

From a document to a video

Send writing you already have and collect a narrated video file.

Client libraries

Complete TypeScript and Python clients with retries and polling.

Errors

The error envelope, every code, and how to retry safely.

Core concepts

Workspaces, Brands, projects, jobs and artifacts in plain language.

Get started

Create

Grow & automate

Integrate

Build reliably

Operate

Prerequisites

Make your first calls

Long-running work returns a job

Next steps

From a document to a video

Client libraries

Errors

Core concepts

​Prerequisites

​Make your first calls

​Long-running work returns a job

​Next steps

From a document to a video

Client libraries

Errors

Core concepts

Prerequisites

Make your first calls

Long-running work returns a job

Next steps