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

# Generate Social Clip

> Trim a source segment, crop to 9:16, transcribe, and render TikTok-style multi-style karaoke captions.

## What this workflow does

Given a source video URL and a time range, orchestrates:

1. **Trim** — `in_point` / `out_point` on the video element
2. **Crop to vertical** — `crop_left` / `crop_right` center-crop for 16:9 → 9:16 (auto-computed when omitted)
3. **Transcribe** — `POST /v1/tasks/transcribe` with word-level timestamps
4. **Segment** — group words into caption lines (sentence breaks or pauses > 0.8s)
5. **Style** — optional opening title with `difference` blend motion; caption lines cycle `color` → `box` → `glow` (the first two paint with the text element's `background_color`, which is required for them)
6. **Render** — `POST /v1/renders` at 1080×1920 using the [TikTok Captions](https://docs.framelane.io/renders/recipes/tik-tok-captions.md) recipe as the composition template

### Example user prompt

> Take the section from 00:22:43 to 00:44:56, crop to vertical, add an opening title with Difference blend, then burn in word-timed captions — mix color, box, and glow styles across different fonts.

The agent converts timecodes to seconds (`1363` → `2696`), follows this workflow, and posts the resulting `RenderRequest`.

## Inputs

| Name | Required | Description |
| - | - | - |
| `source_url` | **required** | URL of the source video |
| `start_seconds` | **required** | Clip start in source seconds (convert `HH:MM:SS` first) |
| `end_seconds` | **required** | Clip end in source seconds |
| `opening_title_text` | optional | Display title at clip start with `difference` blend motion |
| `opening_title_duration` | optional | Title visibility in seconds. Default: `3`. |
| `crop_left` | optional | Left crop fraction (0–1). Auto-computed for `16:9` when omitted (\~`0.342`). |
| `crop_right` | optional | Right crop fraction. Defaults to `crop_left`. |
| `source_aspect_ratio` | optional | Used for auto-crop. Default: `"16:9"`. |

## Output

| Name | Description |
| - | - |
| `clip_url` | Signed URL of the rendered 1080×1920 mp4 |
| `render_id` | Render job ID for status polling |

## Timecode conversion

Convert `HH:MM:SS` to seconds before starting the workflow:

```
00:22:43 → 22×60 + 43 = 1363
00:44:56 → 44×60 + 56 = 2696
duration → 2696 − 1363 = 1333 seconds
```

## Vertical crop (16:9 → 9:16)

When `crop_left` / `crop_right` are omitted, center-crop a landscape source:

```
keep_fraction = (9/16) / (source_width / source_height)
crop_each_side = (1 − keep_fraction) / 2
```

For **16:9** source: `crop_left = crop_right ≈ 0.342`.

## Caption line rules

After transcription, the agent:

1. Converts each word's `start`/`end` from milliseconds (the transcript's clock) to seconds by dividing by 1000, then filters words to `[start_seconds, end_seconds]` and offsets to composition time (`0` = clip start)
2. Groups words into lines — split on `.` `?` `!` or a gap > 0.8s between words
3. Skips words inside `opening_title_duration` when a title is set
4. Creates one `text` element per line, each with its **own unique id** (`cap-0`, `cap-1`, …) — duplicate element ids are a blocking `DUPLICATE_ELEMENT_ID` error
5. Sets each line's `time` to the first word's `start` and `duration` to `last_word.end − time`
6. Cycles `word_animation.style`: `color` → `box` → `glow` → `color` … . **`color` and `box` paint with `background_color`, so that field is required on those two** — omit it and the request 422s (an absent value resolves to opaque black on the renderer, i.e. an invisible highlight). `glow` does not need it.

Word timestamps in `word_animation.words` are **absolute composition seconds** — the same clock as each text element's `time`. See [Word Animation Examples](https://docs.framelane.io/renders/examples/word-animation.md).

## Render composition template

Follow the [TikTok Captions recipe](https://docs.framelane.io/renders/recipes/tik-tok-captions.md) for element shapes. Minimal skeleton:

```json theme={null}
{
  "width": 1080,
  "height": 1920,
  "duration": 1333,
  "frame_rate": 30,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn-user.framelane.io/uploads/.../podcast.mp4",
      "in_point": 1363,
      "out_point": 2696,
      "crop_left": 0.342,
      "crop_right": 0.342,
      "volume": 50
    },
    {
      "type": "text",
      "id": "title",
      "text": "Albert",
      "font_family": "Alfa Slab One",
      "text_color": "#FFFFFF",
      "font_size": 260,
      "x": "50%",
      "y": "70%",
      "time": 0,
      "duration": 3,
      "motion": [{ "type": "difference", "time": 0, "duration": 3 }]
    },
    {
      "type": "text",
      "id": "cap-0",
      "text": "When I came to you with those calculations",
      "time": 4.496,
      "duration": 2.493,
      "background_color": "#e8734a",
      "word_animation": {
        "style": "color",
        "words": [
          { "text": "When", "start": 4.496, "end": 4.577 }
        ]
      }
    }
  ]
}
```

Each additional caption line is another `text` element with the next unique id (`cap-1`, `cap-2`, …) and the next style in the cycle.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.