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

# Clips

> Turn long-form video into platform-ready short clips — AI detects the best moments, tracks speakers, and renders with karaoke captions.

Upload a podcast, interview, or webinar — Clips AI finds the best moments, crops to speaker, adds captions, and renders vertical/horizontal/square clips ready to publish across every platform.

## Pipeline

<Steps>
  <Step title="Upload or import">
    Upload via multipart (large files) or paste a public URL. Autoposting downloads, normalizes, and extracts duration metadata.
  </Step>

  <Step title="AI detection">
    Audio is transcribed with word-level timestamps. AI scores segments for virality, hook strength, and retention. Face detection builds per-speaker crop keyframes.
  </Step>

  <Step title="Review candidates">
    AI-ranked clip candidates appear with scores for `hook`, `retention`, `clarity`, and `visual`. Select a candidate and choose a layout.
  </Step>

  <Step title="Render">
    Dispatch a render job. Track progress via `GET /clips/:id`. Credits are deducted only on successful completion.
  </Step>

  <Step title="Publish">
    Download the rendered clip or create a post draft pre-filled with the video for direct platform publishing.
  </Step>
</Steps>

## Import via URL

```bash theme={null}
curl -X POST https://app.autoposting.ai/api-proxy/clips/import-url \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "brand_id",
    "url": "https://example.com/episode-42.mp4",
    "title": "Episode 42"
  }'
```

Poll `GET /clips/:id` for processing status — the `status` field moves from `processing` to `ready` when candidates are generated.

## Layouts

| Layout | Best For |
| - | - |
| **Focus** | Single or dominant speaker — dynamic reframe |
| **Split** | Two-person conversations — speakers stacked top/bottom |
| **Split + Caption Bar** | Heavy dialogue — dedicated caption bar below split |
| **Cinema** | B-roll, demos, wide shots — full source frame |
| **Auto** | Let AI pick based on face count and scene analysis |

<Note>
  Split layout requires at least 5 qualifying two-face frames spanning more than 3 seconds. If `splitEligible: false`, Split options are disabled and render falls back to Focus.
</Note>

## Submit a Render

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://app.autoposting.ai/api-proxy/clips/:clipId/render \
    -H "Authorization: Bearer sk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "editRevision": 3,
      "candidateId": "candidate_id",
      "formats": ["9:16"]
    }'
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(`https://app.autoposting.ai/api-proxy/clips/${clipId}/render`, {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      editRevision: 3, // current value from GET /clips/:clipId
      candidateId: "candidate_id",
      formats: ["9:16"],
    }),
  });
  const { data } = await res.json();
  // data.jobIds — track via GET /clips/:clipId
  ```
</CodeGroup>

`editRevision` must match the clip's current value from `GET /clips/:clipId`; a stale value returns `409`.

## Create a Post Draft

```bash theme={null}
curl -X POST https://app.autoposting.ai/api-proxy/clips/:clipId/create-draft \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "candidateId": "candidate_id", "aspectRatio": "9:16" }'
```

Returns `data.postId`. Publish or schedule it like any other post.

## Output Formats

| Composition | Resolution | Platforms |
| - | - | - |
| `clip-vertical` | 1080×1920 | TikTok, Instagram Reels, YouTube Shorts |
| `clip-horizontal` | 1920×1080 | YouTube, LinkedIn |
| `clip-square` | 1080×1080 | Instagram feed, LinkedIn square |

## Credit Costs

| Operation | Credits |
| - | - |
| Render (per clip) | Based on duration and resolution |
| Failed render | 0 — credits are never deducted on failure |

<Tip>
  Set `clipTemplateDefaults` on your brand to pre-configure caption presets and aspect ratios, saving configuration time when generating many clips.
</Tip>

## Status Reference

| Clip Status | Description |
| - | - |
| `uploading` | Multipart upload in progress |
| `processing` | Transcription, AI detection, face tracking running |
| `ready` | Candidates generated and available for review |
| `failed` | Processing pipeline failed |

| Candidate Status | Description |
| - | - |
| `generated` | AI candidate, not yet rendered |
| `rendering` | Render job dispatched |
| `completed` | Render finished — download URL available |
| `failed` | Render failed — no credits consumed |

<CardGroup cols={2}>
  <Card title="Posts" icon="paper-plane" href="/concepts/posts">
    Publish rendered clips as scheduled posts across platforms.
  </Card>

  <Card title="Brands" icon="building" href="/concepts/brands">
    Set default clip templates and aspect ratios per brand.
  </Card>

  <Card title="Carousels" icon="images" href="/concepts/carousels">
    Turn topics into multi-slide carousels instead of video clips.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Upload, render, and download endpoint reference.
  </Card>
</CardGroup>


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