# Storyboard

Storyboard is an agent-ready UGC video pre-production workspace. Agents can create projects, write and reorder shots, manage reusable characters/products/audio, upload frames, configure a generation provider, start generations, and poll their results.

## Discovery

- Human documentation: https://storyboard.keypiece.ai/docs
- OpenAPI 3.1: https://storyboard.keypiece.ai/api/v1/openapi.json
- API service index: https://storyboard.keypiece.ai/api/v1
- API base URL: https://storyboard.keypiece.ai/api/v1

## Authentication

Create an integration token in Workspace → Integration. Choose Full access for a trusted agent or Scoped access for least privilege. The secret is shown once and stored only as a SHA-256 hash.

Send it on authenticated requests:

Authorization: Bearer sb_live_…

Start with GET https://storyboard.keypiece.ai/api/v1/me. It confirms the account, whether the token has full or scoped access, and its effective scopes. Never put a token in a URL, prompt shared with another party, source control, or client-side logs.

Available scopes: projects:read, projects:write, characters:read, characters:write, products:read, products:write, audio:read, audio:write, generations:read, generations:write

## Operating guidance

- A project is one storyboard; shots are ordered panels within it.
- Shared characters, products, and audio can be attached to shots.
- Generation is asynchronous. A POST returns 202; poll the returned generation until status is no longer running.
- OpenRouter video is supported as a first-class provider. Configure it with PUT https://storyboard.keypiece.ai/api/v1/settings/generation using provider `openrouter`; Seedance presets are returned by GET. Discover the live catalogue at GET https://storyboard.keypiece.ai/api/v1/settings/generation/models?provider=openrouter, then send any current video `provider/model` id.
- Model capabilities are checked at run time. Unsupported duration, resolution, aspect, frame, audio, or seed inputs are omitted or mapped and recorded in the generation's `warnings`.
- A running job remains bound to the provider that started it, even if the account activates another provider before the next poll.
- Errors use { "error": { "code", "message", "details" } }. Branch on code.
- Use the OpenAPI document for request/response schemas and x-required-scopes.

## Endpoints

- GET    /api/v1 — Service index
- GET    /api/v1/me — Who am I
- GET    /api/v1/projects — List projects [projects:read]
- POST   /api/v1/projects — Create a project [projects:write]
- GET    /api/v1/projects/{projectId} — Retrieve a project [projects:read]
- PATCH  /api/v1/projects/{projectId} — Update a project [projects:write]
- DELETE /api/v1/projects/{projectId} — Delete a project [projects:write]
- GET    /api/v1/projects/{projectId}/shots — List shots [projects:read]
- POST   /api/v1/projects/{projectId}/shots — Create a shot [projects:write]
- GET    /api/v1/projects/{projectId}/shots/{shotId} — Retrieve a shot [projects:read]
- PATCH  /api/v1/projects/{projectId}/shots/{shotId} — Update a shot [projects:write]
- DELETE /api/v1/projects/{projectId}/shots/{shotId} — Delete a shot [projects:write]
- POST   /api/v1/projects/{projectId}/shots/reorder — Reorder the sequence [projects:write]
- PUT    /api/v1/projects/{projectId}/shots/{shotId}/frame — Upload a panel frame [projects:write]
- GET    /api/v1/projects/{projectId}/shots/{shotId}/variations — List variations [projects:read]
- GET    /api/v1/characters — List characters [characters:read]
- POST   /api/v1/characters — Create a character [characters:write]
- GET    /api/v1/characters/{characterId} — Retrieve a character [characters:read]
- PATCH  /api/v1/characters/{characterId} — Update a character [characters:write]
- DELETE /api/v1/characters/{characterId} — Delete a character [characters:write]
- GET    /api/v1/products — List products [products:read]
- POST   /api/v1/products — Create a product [products:write]
- GET    /api/v1/products/{productId} — Retrieve a product [products:read]
- PATCH  /api/v1/products/{productId} — Update a product [products:write]
- DELETE /api/v1/products/{productId} — Delete a product [products:write]
- GET    /api/v1/audio — List audio tracks [audio:read]
- POST   /api/v1/audio — Create an audio track [audio:write]
- GET    /api/v1/audio/{audioId} — Retrieve an audio track [audio:read]
- PATCH  /api/v1/audio/{audioId} — Update an audio track [audio:write]
- DELETE /api/v1/audio/{audioId} — Delete an audio track [audio:write]
- POST   /api/v1/projects/{projectId}/shots/{shotId}/generate — Generate one variation [generations:write]
- POST   /api/v1/projects/{projectId}/generations — Generate a draft [generations:write]
- POST   /api/v1/projects/{projectId}/generations/{generationId}/poll — Advance a running job [generations:write]
- GET    /api/v1/projects/{projectId}/generations — List generation jobs [generations:read]
- GET    /api/v1/projects/{projectId}/generations/{generationId} — Retrieve a generation job [generations:read]
- GET    /api/v1/settings/generation — Read the video model setup [generations:read]
- GET    /api/v1/settings/generation/models — Discover video models [generations:read]
- PUT    /api/v1/settings/generation — Choose the active model [generations:write]
- DELETE /api/v1/settings/generation — Forget a provider key [generations:write]