Sources and Clips

Sources are long-form media objects: webinars, recordings, podcasts, demos, interviews, calls, and other video or audio inputs. The source workflow turns those inputs into transcripts, shots, thumbnails, candidate moments, and .ws clip documents.

Upload Source Media

POST/api/sources/upload

Upload long-form source

Uploads video or audio intended for preprocessing.

bash
curl -X POST "$WORKSHOP_URL/api/sources/upload" \
  -H "x-api-key: $WORKSHOP_API_KEY" \
  -F "file=@webinar.mp4"

Register Source

POST/api/sources

Register a source

Creates a source from an uploaded asset ID or remote URL.

json
{
  "name": "Q2 Webinar",
  "assetId": "asset_abc123"
}

List And Read Sources

Route Purpose
GET /api/sources List sources
GET /api/sources/{id} Read source metadata, transcript chunks, shots, thumbnails, and diagnostics
DELETE /api/sources/{id} Delete a source
GET /sources/{id}/media Public media route for source media
GET /sources/{id}/thumbnails/{thumbnailId} Public media route for generated thumbnails

Preprocess Source

POST/api/sources/{id}/preprocess

Start preprocessing

Runs source analysis to produce transcript chunks, shot metadata, thumbnails, and diagnostics.

GET/api/sources/{id}/preprocess

Read preprocessing status

Returns preprocessing state for a source.

Generate Clip Candidates

POST/api/clips/candidates

Generate candidates

Returns candidate clip windows for a preprocessed source.

json
{
  "sourceId": "src_abc123",
  "goal": "Find a punchy 30-second product proof moment for executives",
  "maxCandidates": 5
}

Refine A Candidate

POST/api/clips/candidates/refine

Refine selection

Adjusts a candidate or explicit time window using transcript and source metadata.

Draft Or Persist A Clip Document

Route Purpose
POST /api/clips/draft Create an in-memory .ws clip draft
POST /api/clips/documents Create and persist a clip document
POST /api/clips/documents/{id}/redraft Redraft an existing clip document
GET /api/clips/documents/{id}/export Export a clip document as .ws text or JSON
  1. Upload or register a source.
  2. Start preprocessing.
  3. Read source metadata, transcript chunks, shots, and thumbnails.
  4. Ask the agent to select a window with explicit start and end seconds.
  5. Create a clip document.
  6. Compile and render the document only after review.

Next Steps

  • Documents - persisted .ws documents
  • MCP - source and clip tools for agents
  • Assets - supporting media uploads