> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sigmora.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Video, shorts & 3D

> The public video contract and its Video Curriculum execution boundary.

## Public product API

Video Curriculum is an execution service, not a second customer-facing API.
Customer integrations use the authenticated, metered Sigmora contract:

| Operation         | Public endpoint          | Execution                            |
| ----------------- | ------------------------ | ------------------------------------ |
| Narrated video    | `POST /v1/video/render`  | Video Curriculum render queue        |
| Short derivatives | `POST /v1/video/shorts`  | Video Curriculum derivative pipeline |
| Text to 3D        | `POST /v1/3d/from-text`  | Video Curriculum asset queue         |
| Image to 3D       | `POST /v1/3d/from-image` | Video Curriculum asset queue         |
| Result polling    | `GET /v1/jobs/{jobId}`   | Unified job facade                   |

The exact request and response schemas in the **API Reference** are generated
from the same route table that handles requests. `GET /v1/capabilities` reports
whether this deployment can currently serve each operation.

## Why the backend has more routes

Video Curriculum also exposes authenticated service routes for worker and
operator concerns: queue claims, catalogue inspection, capabilities, logs,
cancel, artifact download, and provenance verification. Those routes are used
by Sigmora's server-side adapters and are intentionally not parallel public
customer contracts.

This boundary keeps tenant authentication, credit metering, idempotency, error
codes, and job polling consistent. A customer should never need
`VC_SERVER_SECRET` or call `vc.sigmora.org` directly.

## Retry and result rules

* Send a stable `Idempotency-Key` for each logical POST.
* Reuse the same key only with the same request body.
* Treat `202` as acceptance, not completion.
* Poll `GET /v1/jobs/{jobId}` and branch on `status`.
* A job owned by another workspace returns `404`.
* A curriculum job-store outage returns retryable `503 upstream_unavailable`;
  it is never disguised as a missing job.

<Note>
  Internal queue and catalogue routes are operational APIs, not unexposed
  sellable capabilities. New sellable video operations must first be added to
  the public route table, generated OpenAPI, capability catalogue, MCP tools,
  pricing, and tests.
</Note>