Clips Overview

Clips capture a point in a transcribed episode and asynchronously generate a focused excerpt with text, takeaways, and playable media.

Typical workflow

Create a Clip with an Episode sequence number and a non-negative integer playback point.
Poll the Clip detail endpoint until status is done or failed.
When the Clip is ready, use its text and takeaways, play the signed media URL, or export it to Markdown, Notion, or Readwise.

Clip statuses

Status	Description
`waiting`	The Clip is queued for generation.
`processing`	The Clip is being generated.
`done`	Generation completed. Check `exportable` before exporting.
`failed`	Generation failed.

Clip resource


type Clip = {
  id: number,
  episodeId: string,
  episodeSeq: number,
  episodeTitle: string,
  episodeCover: string | null,
  podcastName: string,
  podcastCover: string | null,
  title: string,
  takeaways: string[],
  content: string | null,
  // Requested playback point in seconds
  point: number,
  // Generated excerpt boundaries in seconds
  clipStart: number | null,
  clipEnd: number | null,
  status: "waiting" | "processing" | "done" | "failed",
  exportable: boolean,
  // Unix timestamp in seconds
  createdAt: number,
}

All Clip endpoints are scoped to the authenticated user. A missing Clip and a Clip owned by another user both return 404 not_found.

Media URLs

List and create responses do not include media URLs. The Get Clip endpoint signs ready media for 24 hours and adds mediaUrl, mediaType, and mediaUrlExpiresAt. Request the detail again after the URL expires.

Pagination

The user Clips list uses a zero-based page and a pageSize with a default of 20 and a maximum of 50. The response does not include a total count.