Clip Model

Clip objects are returned in the clips array when GET /workflow-results/{triggerId} finishes with status: "Completed" and in the clip field from GET /clip. Use id as clipId for update and render calls. Workflow result responses return the basic clip fields listed below. GET /clip returns the latest saved clip document and can include additional metadata, source URLs, subtitle configuration, and legacy aliases. Fields are included when available, so some values may be omitted on a given clip. Use renderedUrl as the preview video when present, then call POST /render when you need a finalized export.

Preserved transcript fields

New clips from organizations with transcript reuse enabled can include:

Field	Meaning
`wordTranscriptJSON`	Flat timed word array for the clip’s current media clock. `transcriptUrl` is its alias.
`selectionTranscriptJSON`	Immutable original source transcript and sentence catalog used for selection.
`renderedTranscriptJSON`, `renderedTranscriptProvenance`	Optional transcript and verified clock for delivered media. The editable clip retains its own word transcript and alias.
`selectionTranscriptRequired`	Source preparation must be repaired if a required artifact is unavailable.
`wordTranscriptTimingVersion`	`2` means raw speech edges. Legacy arrays may contain caption gap padding.
`wordTranscriptProvider`	Provider that succeeded, including a fallback provider.
`transcriptProvenance`	Source artifact ID, working revision ID, current media clock, ordered timestamp mapping, and stable diarization namespace.

Preserved words include stable source word/sentence IDs and sentence-edge markers. Repeated montage ranges have separate occurrence IDs. Text corrections and punctuation changes preserve speech timing and the original catalog.

Basic Example

{
  "id": "0e3b1690-3bad-42cc-810d-87fd433054b8",
  "title": "Startup Founder: You're Your Startup's Biggest Threat",
  "bio": "An experienced startup founder and investor explains a key startup risk.",
  "keywords": ["startup", "founder psychology", "self-awareness"],
  "people": ["Startup Founder"],
  "duration": 51.724999,
  "startTimestamp": 0.0,
  "endTimestamp": 51.724999,
  "timestampBoundary": {
    "start": 0.0,
    "end": 30.0
  },
  "aspectRatio": "16:9",
  "renderedUrl": "https://cdn.overlap.ai/fe249157-6be2-4fce-9aec-961f800604f1.mp4",
  "thumbnailURL": "https://cdn.overlap.ai/thumbnails/ce99b3c5-4d5d-4cc4-ae69-b835d23fe77a_thumb.jpg",
  "viralityScore": 89.5
}

Basic Properties

These fields may appear in clips returned from workflow result endpoints and GET /clip.

Property	Type	Description
`id`	string	Unique identifier for the clip. Use this as `clipId` for `/update-clip` and `/render`.
`title`	string	Clip title.
`bio`	string	Short contextual description for the clip.
`keywords`	string[]	Keywords or tags associated with the clip.
`people`	string[]	People or speakers featured in the clip.
`duration`	number	Total duration of the clip in seconds.
`startTimestamp`	number	Timestamp, in seconds, where the clip starts in the source video. For livestream episodes the “source video” is the processing chunk, so this is chunk-relative — use `episodeOffsetSeconds` for the show-absolute position.
`endTimestamp`	number	Timestamp, in seconds, where the clip ends in the source video.
`segments`	Segment[]	Keep-ranges when the clip has been trimmed, in clip-relative seconds: `{ "startSeconds": number, "endSeconds": number }` (0 = the clip’s start). Absent or empty when untrimmed. Writable via update — see Update clip.
`chunkIndex`	number	For livestream-episode clips: index of the processing chunk this clip came from.
`episodeOffsetSeconds`	number	For livestream-episode clips (single-clip get only): absolute offset of the clip on the full episode timeline, reconstructed from the chunk index and chunk length. Approximate to within a few seconds.
`timestampBoundary`	object	Object defining the clipping boundary.
`timestampBoundary.start`	number	Start boundary, in seconds, for clip extraction.
`timestampBoundary.end`	number	End boundary, in seconds, for clip extraction.
`aspectRatio`	string	Clip aspect ratio, such as `"16:9"` or `"9:16"`.
`renderedUrl`	string	Public preview video URL when available. May be omitted if the clip has not been rendered or does not have a preview URL yet.
`rawUrl`	string	Raw clip URL when available.
`thumbnailURL`	string	Thumbnail image URL.
`transcriptUrl`	string	JSON transcript URL when available.
`fps`	number	Frames per second when available.
`videoHeight`	number	Video height in pixels when available.
`videoResolution`	string	Video resolution when available, such as `"1920x1080"`.
`viralityScore`	number	Score estimating predicted clip performance.

Additional `GET /clip` Properties

These fields are returned only by GET /clip when they exist on the saved clip document. They are not part of the basic clip object returned by workflow result endpoints.

{
  "companyId": "org_2yCncPJwBymLmSQlC9Vwk6rHG3e",
  "createdAt": "Tue, 09 Jun 2026 07:08:02 GMT",
  "sourceUrl": "https://storage.googleapis.com/overlap-source-videos/source.mp4",
  "subtitleConfig": {
    "fontSize": "28",
    "maxCharsPerLine": 20,
    "subtitleY": 50,
    "speakerStyles": {
      "0": {
        "fontColor": "#ffffff",
        "fontFamily": "TheBoldFont",
        "animationStyle": "spring-word"
      }
    }
  }
}

Property	Type	Description
`url`	string	Public clip video URL when available.
`publicURL`	string	Public clip video URL when available. Often the same asset as `url` or `extendedClipURL`.
`extendedClipURL`	string	Public URL for the generated or extended clip media.
`renderedThumbnailUrl`	string	Thumbnail image URL generated during rendering.
`wordTranscriptJSON`	string	Word-level transcript JSON URL when available. Often the same asset as `transcriptUrl`.
`companyId`	string	Company or organization id that owns the clip.
`enterpriseId`	string	Enterprise organization id when the clip belongs to an enterprise account.
`teamId`	string	Team identifier associated with the clip.
`workflowId`	string	Workflow id that produced the clip when available.
`runId`	string	Workflow run id or generation run id when available.
`taskId`	string	Generation task id associated with the clip.
`taskID`	string	Legacy uppercase alias for `taskId`.
`sourceId`	string	Source media id associated with the clip.
`sourceID`	string	Legacy uppercase alias for `sourceId`.
`sourceInputId`	string	Source input id when the clip was produced from a workflow input.
`clipHash`	string	Stable hash for the generated clip media or transcript source when available.
`createdAt`	string	Creation timestamp for the saved clip document.
`normalizedUrl`	string	Normalized or proxied source video URL when available.
`originalUrl`	string	Original source media URL submitted to Overlap.
`sourceUrl`	string	Source media URL associated with the clip.
`speakers`	string[]	Speaker names or identifiers when speaker data is available.
`subtitleConfig`	object	Subtitle rendering configuration, including optional base style fields and `speakerStyles`.
`subtitleId`	string	Identifier for the selected subtitle preset when available.
`subtitleY`	number	Subtitle vertical position when stored separately from `subtitleConfig`.

Some clip responses include legacy aliases, such as taskID with taskId or sourceID with sourceId. Prefer the camelCase fields in new integrations.

Downloading media URLs

Supported public media fields can use cdn.overlap.ai instead of a direct storage address as the public CDN rollout is enabled. Treat returned URLs as opaque: do not replace hostnames, remove path prefixes, or strip query parameters. Use the clip ID, rather than a storage URL, as the clip’s identity. Fetch a returned public media URL with a normal GET request. The media GET does not need your Overlap API key; keep that key on requests to the Overlap API only. Public CDN v1 URLs are unsigned and non-expiring, and anyone with a URL can download or forward it. Private or signed URLs from other providers retain their own access requirements. Browser JavaScript additionally depends on the media host’s CORS policy. The public CDN v1 rollout targets GET/HEAD from any website, with no credentials; do not assume that older or alternate storage hosts already allow arbitrary browser origins. Server-side GET downloads are not subject to browser CORS. Use a finalized renderUrl returned by POST /render to download the edited composition. Downloading a source URL retrieves the source object, not the cuts, captions, crop instructions, or overlays described by editing JSON.

Get Results

Retrieve clips after a workflow completes

Update Clip

Save editable fields before rendering

Render Clip

Render a finalized export

Workflows

Clips

Posts & Analytics

Errors

Preserved transcript fields

Basic Example

Basic Properties

Additional `GET /clip` Properties

Downloading media URLs

Get Results

Update Clip

Render Clip

​Preserved transcript fields

​Basic Example

​Basic Properties

​Additional GET /clip Properties

​Downloading media URLs

​Related Endpoints

Get Results

Update Clip

Render Clip

Preserved transcript fields

Basic Example

Basic Properties

Additional `GET /clip` Properties

Downloading media URLs

Related Endpoints