> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overlap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Clip

> Save editable clip fields before rendering a finalized export

### Endpoint

```http theme={null}
POST https://api.joinoverlap.com/update-clip
```

Use this endpoint after a user reviews or edits a clip. It updates the saved clip document only; it does not render a new video.

### Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Request Body

```json theme={null}
{
  "companyId": "your-company-id",
  "clipId": "clip-id-from-results",
  "updates": {
    "title": "Product Launch Highlights",
    "bio": "Key moments from the product launch webinar.",
    "subtitleConfig": {
      "subtitleY": 50
    }
  },
  "merge": true
}
```

Send editable fields inside `updates`. For convenience, editable fields can also be sent at the top level beside `companyId` and `clipId`.

When `merge` is `true` or omitted, nested config objects such as `subtitleConfig` and `titleConfig` are shallow-merged with the existing clip config. Set `merge` to `false` only when you want to replace those nested objects.

## Editable Fields

| Field                               | Type                  | Description                                  |
| ----------------------------------- | --------------------- | -------------------------------------------- |
| `title`                             | string                | Clip title.                                  |
| `bio`                               | string                | Clip description.                            |
| `keywords`                          | string\[]             | Clip keywords.                               |
| `people`                            | string\[]             | People or speakers associated with the clip. |
| `segments`                          | Segment\[]            | Final keep segments for the clip.            |
| `duration`                          | number                | Clip duration in seconds.                    |
| `startTimestamp` / `endTimestamp`   | number                | Source video timestamps.                     |
| `timestampBoundary`                 | TimestampBoundary     | Clip extraction boundary.                    |
| `subtitleConfig`                    | SubtitleConfig        | Subtitle rendering configuration.            |
| `titleConfig`                       | TitleConfig           | Title overlay configuration.                 |
| `watermarkConfig`                   | WatermarkConfig       | Single watermark configuration.              |
| `backgroundMusicOption`             | BackgroundMusicOption | Background music configuration.              |
| `endCardOption` / `end_card_option` | EndCardOption         | End card configuration.                      |

Unsupported fields return `UNSUPPORTED_CLIP_FIELDS`.

## Field Shapes

### Segment

```json theme={null}
{
  "start": 12.4,
  "end": 36.8,
  "playbackRate": 1
}
```

| Field          | Type   | Description                               |
| -------------- | ------ | ----------------------------------------- |
| `start`        | number | Segment start time in source seconds.     |
| `end`          | number | Segment end time in source seconds.       |
| `playbackRate` | number | Optional playback speed for this segment. |

### TimestampBoundary

```json theme={null}
{
  "start": 10,
  "end": 45
}
```

| Field   | Type   | Description                       |
| ------- | ------ | --------------------------------- |
| `start` | number | Start boundary in source seconds. |
| `end`   | number | End boundary in source seconds.   |

### SubtitleConfig

`subtitleConfig` follows the frontend subtitle style schema. You can update the base subtitle style and optional per-speaker styles.

```json theme={null}
{
  "fontColor": "#FFFFFF",
  "fontFamily": "Forma-DJR",
  "fontSize": "42",
  "fontWeight": "900",
  "backgroundColor": "transparent",
  "backgroundOpacity": 0,
  "maxCharsPerLine": 30,
  "subtitleX": 50,
  "subtitleY": 50,
  "speakerStyles": {
    "0": {
      "subtitleY": 50
    }
  }
}
```

Common fields include `fontColor`, `fontFamily`, `fontSize`, `fontWeight`, `backgroundColor`, `backgroundOpacity`, `backgroundFillStyle`, `backgroundPadding`, `captionPosition`, `textAlign`, `outlineColor`, `outlineWidth`, `shadowColor`, `shadowBlur`, `shadowEnabled`, `textCase`, `maxCharsPerLine`, `subtitleX`, `subtitleY`, and `speakerStyles`.

`speakerStyles["0"]` represents the first speaker in the video.

### TitleConfig

`titleConfig` controls generated or explicit title overlay styling.

```json theme={null}
{
  "text": "Product Launch Highlights",
  "prompt": "Create a concise title for this clip",
  "fontFamily": "Roboto",
  "fontWeight": "500",
  "fontColor": "#000000",
  "fontSize": 64,
  "backgroundColor": "#FFFFFF",
  "backgroundOpacity": 1,
  "backgroundStyle": "wrap",
  "textAlign": "center",
  "yPosition": 0.23,
  "duration": 4,
  "allCaps": false
}
```

Common fields include `text`, `prompt`, `fontFamily`, `fontUrl`, `fontWeight`, `fontColor`, `fontSize`, `lineHeight`, `characterSpacing`, `padding`, `verticalPadding`, `borderRadius`, `backgroundColor`, `backgroundOpacity`, `textShadow`, `boxShadow`, `xPosition`, `yPosition`, `positionDynamically`, `avoidFaces`, `maxWidthPercent`, `targetHeightPercent`, `duration`, `fadeDuration`, `allCaps`, `backgroundStyle`, `textAlign`, `fontScale`, and `lineMargin`.

### WatermarkConfig

| Field               | Type    | Description                                                           |
| ------------------- | ------- | --------------------------------------------------------------------- |
| `enabled`           | boolean | Shows or hides the watermark.                                         |
| `url`               | string  | Public watermark image URL.                                           |
| `position`          | number  | Grid position used by the renderer.                                   |
| `size`              | number  | Watermark size.                                                       |
| `padding`           | number  | Padding from the frame edge.                                          |
| `opacity`           | number  | Watermark opacity from `0` to `1`.                                    |
| `x` / `y`           | number  | Optional custom position as a percentage of video width/height.       |
| `startOffset`       | number  | Seconds after the clip starts before the watermark appears.           |
| `endOffset`         | number  | Seconds before the clip ends when the watermark disappears.           |
| `animationDuration` | number  | Intro/outro transition duration in seconds.                           |
| `introTransitionId` | string  | Optional intro transition preset ID, such as `fade` or `slideInLeft`. |
| `outroTransitionId` | string  | Optional outro transition preset ID, such as `fade` or `zoomOut`.     |

### BackgroundMusicOption

| Field          | Type   | Description                   |
| -------------- | ------ | ----------------------------- |
| `id`           | string | Music asset identifier.       |
| `name`         | string | Display name.                 |
| `url`          | string | Public audio URL.             |
| `thumbnailUrl` | string | Optional music thumbnail URL. |
| `duration`     | number | Track duration in seconds.    |
| `volume`       | number | Volume from `0` to `1`.       |

### EndCardOption

| Field              | Type    | Description                                        |
| ------------------ | ------- | -------------------------------------------------- |
| `url`              | string  | Public image or video URL for the end card.        |
| `duration`         | number  | End card duration in seconds.                      |
| `secondsBeforeEnd` | number  | When the end card starts relative to the clip end. |
| `isVideo`          | boolean | Whether the end card asset is a video.             |
| `opacity`          | number  | End card opacity from `0` to `1`.                  |
| `videoDuration`    | number  | Source duration for video end cards.               |
| `volume`           | number  | Volume for video end cards.                        |

<RequestExample>
  ```javascript javascript theme={null}
  const response = await fetch("https://api.joinoverlap.com/update-clip", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.OVERLAP_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      companyId: process.env.OVERLAP_COMPANY_ID,
      clipId: "clip-id-from-results",
      updates: {
        title: "Product Launch Highlights",
        subtitleConfig: {
          subtitleY: 50
        }
      }
    })
  });

  const data = await response.json();
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.joinoverlap.com/update-clip" \
       -H "Authorization: Bearer $OVERLAP_API_KEY" \
       -H "Content-Type: application/json" \
       -d '{
             "companyId": "'"$OVERLAP_COMPANY_ID"'",
             "clipId": "clip-id-from-results",
             "updates": {
               "title": "Product Launch Highlights",
               "subtitleConfig": {
                 "subtitleY": 50
               }
             }
           }'
  ```
</RequestExample>

## Response

```json theme={null}
{
  "clipId": "clip-id-from-results",
  "status": "success",
  "updatedFields": ["title", "subtitleConfig"],
  "updates": {
    "title": "Product Launch Highlights",
    "subtitleConfig": {
      "subtitleY": 50
    }
  }
}
```

<Card title="Render Clip" icon="play" color="#ff2700" href="/api-reference/render">
  Render the updated clip into a finalized export
</Card>