Projects

A project holds one piece of work: the script, the footage, the renders and the conversations that produced them. Every capability call names its project with projectId, and the dashboard shows the same projects your integration creates.

Create a project

mediaType is video or audio. A video project also needs videoPath, the production path that fits the work — general fits anything. title is optional; an untitled project is valid. Projects are private to their creator unless you set visibility to workspace.

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

import os
import requests

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

project = session.post(
    "https://api.sigmora.org/v1/projects",
    headers={"Idempotency-Key": "launch-film-project-001"},
    json={"title": "Launch film", "mediaType": "video", "videoPath": "general"},
    timeout=30,
).json()["project"]
print(project["id"])

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

const { project } = await fetch("https://api.sigmora.org/v1/projects", {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "launch-film-project-001" },
  body: JSON.stringify({ title: "Launch film", mediaType: "video", videoPath: "general" }),
}).then((r) => r.json());
console.log(project.id);

The response is 201 with the new project:

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

Idempotency-Key is required. Retrying with the same key and body returns the same project, so a timeout never creates a duplicate. Specialist video paths include talking-head, faceless-explainer, product-demo, interview-podcast, course-video, how-to-video, chess-video and more; the reference lists every value. Pass the same projectId to each related call. The script, render and thumbnail land in one project you can read back in a single request:

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

Every capability response repeats the projectId it filed the work under, so you can confirm where it went.

A projectId from another workspace answers 404 not_found and charges nothing. The work is never filed somewhere else instead. Sigmora answers not_found rather than forbidden on purpose, so ids cannot be used to probe what exists in other workspaces.

List projects

GET /v1/projects lists active projects visible to the key’s user. Use status=archived or status=all to include archived ones, and page with cursor:

curl "https://api.sigmora.org/v1/projects?status=all&limit=50" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"

A page can be empty while hasMore is true when it only passed over other members’ private projects. Keep following nextCursor until it is null — see Pagination.

Rename or archive a project

PATCH /v1/projects/{projectId} takes title, status, or both. Archiving hides a project from the default list and is reversible; there is no API call that permanently deletes a project and the renders you paid for.

curl -X PATCH https://api.sigmora.org/v1/projects/prj_9x2a4c \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "archived"}'

session.patch(
    "https://api.sigmora.org/v1/projects/prj_9x2a4c",
    json={"status": "archived"},
    timeout=30,
).raise_for_status()

await fetch("https://api.sigmora.org/v1/projects/prj_9x2a4c", {
  method: "PATCH",
  headers,
  body: JSON.stringify({ status: "archived" }),
});

Send {"status": "active"} to restore it. Sending an empty title returns the project to untitled.

Variations of a proven format

When a project holds a reference you have broken down — its hook, beats, pacing and call to action — you can ask for up to 1,000 script variants of that format, varying the axes you list: hooks, angles, presenters, voices, languages, aspects, products and music.

Propose the batch

The proposal does not start anything. It returns a quote for the whole batch — variants × the per-variant price — and a signed approval.approval.

curl -X POST https://api.sigmora.org/v1/projects/prj_9x2a4c/variations \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vary-desk-habits-001" \
  -d '{
    "referenceAssetId": "cnt_8f3e2a71",
    "count": 100,
    "axes": { "hooks": ["A", "B", "C"], "angles": ["X", "Y"] }
  }'

Approve it

Send the approval.approval value unchanged to POST /v1/sigma/approvals to start the batch. If the workspace’s auto-approval threshold covers the price, the batch starts immediately and the response carries approval.autoApproved. Only variants not already covered by an identical earlier output are charged, and a variant that fails is refunded.

Follow progress and keep the good ones

Read the batch until batch.status is complete, paging variants with cursor. Then approve or reject variants by id; approving saves each ready variant as a project script.

GET  /v1/projects/{projectId}/variations
GET  /v1/projects/{projectId}/variations/{batchId}?cursor=<nextCursor>
POST /v1/projects/{projectId}/variations/{batchId}/review
     { "variantIds": ["v0000", "v0003"], "decision": "approve" }

Over MCP the same steps are variations_propose, sigma_approve, variations_get and variations_review.

Translate a composition

Translate a cut into up to 10 languages at once. Each language lands in the project as its own editable composition, <title> · <Language>, with the dub’s own words as its transcript:

curl -X POST https://api.sigmora.org/v1/projects/prj_9x2.../translations \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Idempotency-Key: translate-launch-001" \
  -H "Content-Type: application/json" \
  -d '{"languages":["es","pt-BR"],"lipSync":true}'

languages are the provider’s codes (es, fr, pt-BR, ja, …; 108 in all). output is dub (the default) or subtitles, the cheaper path that keeps the original audio. A dub clones each speaker’s voice unless you pass voiceIdentityId; timing: "direct" translates literally in that chosen voice; lipSync re-syncs the mouth. compositionId picks the composition (the project’s first when omitted). Like a variation batch, this only proposes. The answer carries the quote, every language at its per-minute price, and a signed approval.approval. Send that to POST /v1/sigma/approvals to start it: it is charged then, and a language that fails is refunded. Follow each language with:

GET /v1/projects/{projectId}/translations

Each row has its status (ready when its composition is done), what it was charged and targetCompositionId. Over MCP the same steps are translations_propose, sigma_approve and translations_list.

Get started

Create

Grow & automate

Integrate

Build reliably

Operate

Create a project

List projects

Rename or archive a project

Variations of a proven format

Translate a composition

​Create a project

​Keep related work together

​List projects

​Rename or archive a project

​Variations of a proven format

​Translate a composition

Create a project

Keep related work together

List projects

Rename or archive a project

Variations of a proven format

Translate a composition