# Sigmora

> A creator's production API: research a source video and write a script from it,
> edit raw footage into a cut, generate thumbnails, translate and caption, then
> publish. One HTTP call per outcome — these are whole pipelines, not model calls.

Base URL: https://api.sigmora.org
OpenAPI: https://api.sigmora.org/v1/openapi.json
Docs: https://docs.sigmora.org

## Before your first call

- **Auth**: `Authorization: Bearer sk_live_...`. A key is minted by a human in
  Settings → API keys and is **pinned to one workspace** — it carries both the
  workspace billed and the user acted as, so you never send a workspace or user
  id yourself, and cannot act outside the one you were given.
- **Everything costs credits.** Prices are listed below and are also live at
  `GET /v1/capabilities`, which additionally reports whether THIS deployment can
  serve each one. Check it before planning a long sequence; a 3D flow on a
  CPU-only deployment answers `capability_unavailable`, and retrying will not help.
- **Branch on `code`, never on the message.** Every failure returns
  `{ success: false, error, code }`. The wording changes between releases; the
  code does not. `insufficient_credits` means top up. `rate_limited` means honour
  `Retry-After`. `invalid_request` means fix the body — do not retry it unchanged.
- **★ RETRY WITH `Idempotency-Key`, never bare.** Send a unique
  `Idempotency-Key: <your-id>` header on any call that spends. A repeat with the
  same key REPLAYS the stored response instead of doing the work again — without
  it, a retried `video.remix` is charged twice and produces two scripts. This is
  the single most important header for an autonomous caller, because you will
  retry on a timeout and the first attempt may well have succeeded.
- **`projectId` is required** on capability calls: it is the container the work is
  filed under. Create one with `POST /v1/projects` or list existing ones.
- **Async operations return `{ jobId }`**, not a result. Poll `GET /v1/jobs/{jobId}`
  until `status` is `done` or `failed`. `awaiting_review` means a human must
  approve a cut before anything renders — **polling will not advance it**, so tell
  the user rather than waiting.

## Containers

- `/v1/channels` — a channel is the BRAND: voice, colour, products, destinations.
  Creating one needs only a name; everything else inherits the workspace. Many
  channels per workspace, and a project belongs to exactly one.
- `/v1/products` — what a channel sells. A script can promote these.
- `/v1/projects` — one piece of work; every capability files its output here.

## Capabilities

- `POST /v1/3d/from-text` — Describe an object; receive an animated 3D render of it. (175 credits · async: returns a jobId · needs the GPU backend)
- `POST /v1/3d/from-image` — Upload a photo; receive an animated 3D render of what is in it. (175 credits · async: returns a jobId · needs the GPU backend)
- `POST /v1/video/render` — Send prose, a topic, or a catalogue id; receive a narrated video. (300 credits · async: returns a jobId)
- `POST /v1/video/shorts` — Turn a finished render into platform-shaped short-form clips. (40 credits)
- `POST /v1/video/edit` — Send raw footage and a brief; receive an edited cut plus shorts. (150 credits per output · async: returns a jobId)
- `POST /v1/video/moments` — Score a transcript and return the moments worth cutting — chosen on meaning, not clock position. (6 credits per transcript-minute)
- `POST /v1/text/script` — Send a seed video; receive a researched, fact-checked script with title options. (150 credits)
- `POST /v1/text/localize` — Translate a transcript into many languages with cue-accurate captions, and optionally dubbed audio. (5 credits per language-minute)
- `POST /v1/text/packaging` — Turn a finished edit's transcript into titles, description, tags and thumbnail prompts, grounded in a channel brief. (20 credits per pass (the video, plus one per short))
- `POST /v1/text/article` — Turn a script and its verified claims into a citation-bearing article (HTML, Markdown, excerpt, tags). (30 credits)
- `POST /v1/video/remix` — Synthesise one original script from up to ten reference videos or transcripts. (300 credits)
- `POST /v1/text/copywrite` — Rewrite content as a native post for one platform. (15 credits)
- `POST /v1/text/research` — Produce a research brief on a topic, in a named domain. (25 credits)
- `POST /v1/text/paraphrase` — Restyle long-form content into a new tone, style and audience. (15 credits)
- `POST /v1/text/questions` — Generate a question set from source text, at a chosen difficulty. (15 credits)
- `POST /v1/text/solve` — Solve a question in a named domain, with worked steps. (15 credits)
- `POST /v1/text/film` — Turn a premise into a three-act screenplay outline. (20 credits)
- `POST /v1/text/adapt` — Adapt a competitor's hook and format into an original short-form script. (15 credits)

### Commodity passthrough

- `POST /v1/image/thumbnail` — Generate a platform-sized thumbnail from a title, with the brief LLM-refined first. (60 credits)
- `POST /v1/audio/music` — Generate music from weighted prompts, up to three minutes. (25 credits per 5 seconds)

## Recipes

**A talking-head script from a YouTube video**
```
POST /v1/text/script
{ "sourceUrl": "https://youtube.com/watch?v=...", "projectId": "...",
  "presenterName": "Ada", "channelName": "Ada Builds",
  "products": [{ "name": "The Course", "description": "...", "type": "course" }] }
```
The source's own channel name never survives — the script is written fresh, and
the presenter/channel you supply are woven in instead. Products get their own
prompt block with rules against inventing links, prices or features.

**A thumbnail that knows what the video says**
```
POST /v1/image/thumbnail
{ "title": "...", "assetId": "<a transcribed asset>", "projectId": "..." }
```
`assetId` pulls the video's own words from the transcript index, so you do not
paste a transcript. Send `transcript` directly and it wins.

**Reuse a transcript instead of paying twice**
`text.localize` and `video.moments` accept `assetId` in place of `transcript`.
Read one with `GET /api/workspaces/{slug}/assets/{assetId}/transcript`.

## Acting on someone's behalf

- **Spending is real money.** A capability call debits a human's balance. Confirm
  before a batch, and prefer `GET /v1/capabilities` over discovering a price by
  being charged it.
- **Publishing reaches an audience.** Scheduled posts are held for approval by
  default — treat that gate as a feature, not an obstacle to route around.
- **Refusals are answers.** `not_found` for an id in another workspace is
  deliberate and identical to a missing one; do not probe for the difference.

## Choosing a call

Each capability is a whole pipeline, so prefer ONE call over assembling a
sequence: `text.script` researches, fact-checks and writes; `video.edit` cuts and
produces shorts. Chaining smaller calls to imitate one of these costs more, takes
longer and gives a worse result.

Side effects, stated plainly so you can decide what needs a human first:

- `/v1/channels`, `/v1/products`, `/v1/projects` — create records. Free, reversible
  (archive, never delete).
- Every capability — **spends credits and cannot be undone**. A failed run is
  refunded; a successful one you did not want is not.
- Publishing — reaches a real audience. Held for approval by default.

## MCP

If your client speaks MCP, prefer it — you get the same work without constructing
HTTP, and the same `sk_live_` key authenticates it.

    endpoint: https://api.sigmora.org/mcp
    transport: Streamable HTTP, JSON-RPC 2.0 (protocol 2025-06-18)
    auth: Authorization: Bearer sk_live_...

Every capability above is a tool, named for its operation id with the dot
replaced by an underscore — `POST /v1/text/script` is the tool `text_script`.
The supporting endpoints are tools too: `projects_create` (call it first — every
capability needs a `projectId`), `projects_list`, `projects_get`, `jobs_get`
(how you poll an async capability), `capabilities_list` and `usage_get`. Tool
schemas, prices and side effects are generated from this same catalogue, so
`tools/list` and this file cannot disagree.

Two differences from the HTTP surface, both because a tool call has no headers:
`Idempotency-Key` is the `idempotencyKey` ARGUMENT on any tool that spends, and
the workspace is an optional `workspace` argument rather than a header (omit it —
your key names its own). Everything else — auth, prices, error codes, project
scoping, job polling — is the same API you would call over HTTP, because it IS
the same handlers.