# Shotmatic API — Full Reference

> Programmatic short-form video creation, clip extraction, and reusable workflows. This is the expanded reference. [/v1/openapi](/v1/openapi) is the OpenAPI contract for most of the resources below; `/v1/calculate-credits` is documented here.

## Base

- Base path: `/v1`
- Content type: `application/json`
- Errors: JSON envelope `{ "error": string, "code"?: string, "details"?: object }`.
- Self-healing validation: code `MISSING_REQUIRED_FIELDS` carries `details.missing` (dotted field paths) and `details.remediation` (how to fix).

## Authentication

- Send `Authorization: Bearer <api_key>`. Keys are SHA-256 hashed, shown once, and enforce scope, revocation, and expiry per request.
- `POST /v1/calculate-credits` requires no authentication.

### Scopes

- `voice_catalog:read`
- `voices:read`
- `voices:write`
- `clip_previews:read`
- `clip_previews:write`
- `embed_tokens:write`
- `speech_previews:read`
- `speech_previews:write`
- `catalog:read`
- `media:read`
- `media:write`
- `videos:read`
- `videos:write`
- `sessions:read`
- `sessions:write`
- `projects:read`
- `projects:write`
- `brand_kits:read`
- `brand_kits:write`
- `presenter_profiles:read`
- `presenter_profiles:write`
- `avatar_profiles:read`
- `avatar_profiles:write`
- `avatar_source_packs:read`
- `avatar_source_packs:write`
- `workflow_profiles:read`
- `workflow_profiles:write`
- `workflow_bindings:read`
- `workflow_bindings:write`
- `clip_tasks:read`
- `clip_tasks:write`
- `workflows:read`
- `workflow_executions:read`
- `workflow_executions:write`
- `webhooks:read`
- `webhooks:write`
- `usage:read`

## Creation surface (video types)

- **Faceless Short** (`simple`)
- **Talking Avatar** (`avatar_video`)
- **Link to Video** (`article_video`)
- **UGC Ad** (`ad_generator`)
- **Clips from Long Video** (`viral_clip`)

Render options: aspect ratios (9:16, 4:5, 1:1, 16:9), media types (images_only, first_only, strong_start, odds, full), image quality (standard, ultra).

## Archetypes (guided creation flows)

- **Brief Video** (`create_video_from_brief`): Fast-path creation from a short brief when the user has not yet chosen a more specific archetype.
- **Listing Teaser** (`create_listing_teaser`): Short real-estate teaser that leads with the best property moments and a crisp CTA.
- **Article Explainer** (`turn_article_into_video`): Convert an article into a concise editorial reel or explainer video with strong pacing and clear narration.
- **Walkthrough Clips** (`turn_walkthrough_into_clips`): Extract short clips from a longer walkthrough or tour and render the most compelling sections.
- **Avatar Spokesperson** (`create_avatar_spokesperson_video`): Create a presenter-style announcement or promo with a chosen voice and a compact script.
- **Launch Film** (`create_launch_film`): Produce a premium hero film for launches, reveal moments, or high-intent campaign creative.
- **Shorts Batch** (`create_shorts_batch`): Create a repeatable batch of related shorts for a campaign, series, or content system.
- **UGC Ad** (`create_ugc_ad`): Turn a product brief, proof points, and call to action into a concise performance ad.
- **Asset First Campaign** (`create_asset_first_campaign`): Start from reusable media assets and build a campaign around them with consistent reuse and variation.

## Credit price sheet

Costs are in credits. Columns are the public `media_type` values.

| Operation | images_only | first_only | strong_start | odds | full |
| --- | --- | --- | --- | --- | --- |
| Video, 4 scenes (standard) | 100 | 141 | 264 | 182 | 264 |
| Video, 4 scenes (ultra) | 137 | 178 | 301 | 219 | 301 |
| Video, 6 scenes (standard) | 140 | 181 | 304 | 263 | 386 |
| Video, 6 scenes (ultra) | 181 | 222 | 345 | 304 | 427 |
| Video, 8 scenes (standard) | 180 | 221 | 344 | 344 | 508 |
| Video, 8 scenes (ultra) | 225 | 266 | 389 | 389 | 553 |
| Talking Avatar, full-frame presenter (from) | 105 | 105 | 105 | 105 | 105 |
| Talking Avatar with supporting visuals, standard (from) | 145 | 186 | 309 | 268 | 391 |

A video costs its images-only price plus 41 credits for each scene its media type animates with a 5-second AI clip: first_only animates the first scene, strong_start the first four, odds every other scene from the first, full every scene. The images-only price covers 4 scenes (4 are counted when a video plans fewer); each scene 5-8 adds 20 credits (22 ultra) and each scene past 8 adds 11 (20 ultra). A faceless (simple) script plans 4 scenes at 15-30 s, 6 at 31-45 s and 8 at 46-180 s; article, ad and audio videos plan 6 at any length (scene labels can plan up to 12). Pass video_type to POST /v1/calculate-credits to price those formats.

Talking Avatar rows are the smallest quote a layout can get. A video's quote is the render (the video price for its supporting scenes, or 100 for a full-frame presenter), its narration (about 1 credit per 15 characters) and presenter time: about 7.2 credits per second of narration on a featured presenter. The presenter is charged for the seconds the narration really lasts, never more than the quote; POST /v1/sessions/{id}/avatar-performance-batches returns the exact quote.

Per-operation flat costs (credits):
- Viral clip, no voice-over: 120 for the source analysis when the clip task is created, then 120 for each rendered clip or compilation
- Viral clip, with voice-over: 240 for the source analysis, then 240 for each rendered clip or compilation
- Script generation: 20
- Animate one scene in the editor (Turn into Video): 41, plus 14 (21 ultra) when the scene has no image yet
- Edit video: same as the original render configuration

Monthly credit allotments by plan:
- free_trial: 140 credits/mo
- explorer: 1200 credits/mo
- daily: 2800 credits/mo
- viral: 5600 credits/mo

Estimate any job without a key via `POST /v1/calculate-credits` — it returns the same per-line-item breakdown, a total, and an approximate USD value.

## MCP

- Hosted Remote MCP endpoint: [`/mcp`](/mcp), authenticated with an API key sent as `Authorization: Bearer <api_key>`, or through OAuth for connector apps such as claude.ai and ChatGPT (the token they receive is a managed API key).
- OAuth authorization server metadata: [`/.well-known/oauth-authorization-server`](/.well-known/oauth-authorization-server).
- Protected-resource metadata: [`/.well-known/oauth-protected-resource/mcp`](/.well-known/oauth-protected-resource/mcp).
- Default tool count: 23.
- Tools: `plan_video`, `get_creation_cost_estimate`, `quote_avatar_session`, `create_session`, `get_session_preview`, `update_session`, `branch_session`, `approve_and_render`, `get_render_status`, `publish_video`, `create_clip_task`, `get_clip_task`, `quote_clip_sections`, `wait_for_clip_task`, `render_clip_sections`, `list_videos`, `get_video`, `upload_media`, `list_media`, `create_sequence`, `pause_sequence`, `resume_sequence`, `get_account`.
- Guides: [MCP server reference](/developer/mcp), [Claude Code guide](/developer/claude-code), [Cursor guide](/developer/cursor), [Codex guide](/developer/codex).
- Catalog reads are resources: `shotmatic://voices`, `shotmatic://archetypes`, `shotmatic://caption-styles`, `shotmatic://overlay-styles`, `shotmatic://visual-styles`, `shotmatic://capabilities`, `shotmatic://pricing/credit-price-sheet`, `shotmatic://docs/live-session-payloads`, `shotmatic://docs/live-render-payloads`, and `shotmatic://docs/llms-full`.

## Resources

- [/v1/capabilities](/v1/capabilities)
- [/v1/calculate-credits](/v1/calculate-credits)
- [/v1/workflow-node-types](/v1/workflow-node-types)
- [/v1/archetypes](/v1/archetypes)
- [/v1/projects](/v1/projects)
- [/v1/sessions](/v1/sessions)
- [/v1/video-plans](/v1/video-plans)
- [/v1/videos](/v1/videos)
- [/v1/clip-previews](/v1/clip-previews)
- [/v1/embed-tokens](/v1/embed-tokens)
- [/v1/clip-tasks](/v1/clip-tasks)
- [/v1/workflow-profiles](/v1/workflow-profiles)
- [/v1/workflow-profile-bindings](/v1/workflow-profile-bindings)
- [/v1/presenter-profiles](/v1/presenter-profiles)
- [/v1/brand-kits](/v1/brand-kits)
- [/v1/caption-styles](/v1/caption-styles)
- [/v1/overlay-styles](/v1/overlay-styles)
- [/v1/visual-styles](/v1/visual-styles)
- [/v1/voice-catalog](/v1/voice-catalog)
- [/v1/voices](/v1/voices)
- [/v1/media](/v1/media)
- [/v1/social-accounts](/v1/social-accounts)
- [/v1/render-runs](/v1/render-runs)
- [/v1/workflows](/v1/workflows)
- [/v1/webhooks/deliveries](/v1/webhooks/deliveries)
- [/v1/api-keys](/v1/api-keys)

## Quickstart

Estimate credits for a full-media, ultra-quality render (keyless):

```bash
curl -X POST https://shotmatic.com/v1/calculate-credits \
  -H 'Content-Type: application/json' \
  -d '{"type":"video","media_type":"full","image_quality":"ultra","duration_seconds":30}'
```

Create a session (interactive draft) with an API key:

```bash
curl -X POST https://shotmatic.com/v1/sessions \
  -H "Authorization: Bearer $SHOTMATIC_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"source":{"kind":"prompt","prompt":"A 20-second luxury condo teaser"},"goal":{"target_platform":"instagram_reels"}}'
```

Create a one-shot video (automated, no approval step):

```bash
curl -X POST https://shotmatic.com/v1/videos \
  -H "Authorization: Bearer $SHOTMATIC_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <unique>' \
  -d '{"source":{"kind":"script","script":"..."},"voice":{"id":"<voice_entity_id>"},"render":{"media_type":"full","image_quality":"ultra"}}'
```

See [/v1/openapi](/v1/openapi) for the request and response schemas it covers.