---
title: "Detect faces/speakers and write layout + keyframes"
method: POST
path: "/api/clips/{id}/auto-reframe"
tags: ["smart"]
---

# Detect faces/speakers and write layout + keyframes

`POST /api/clips/{id}/auto-reframe`

## Request

- Base URL: `https://cliponit.app`
- URL: `https://cliponit.app/api/clips/{id}/auto-reframe`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `session`
  - OAuth 2 (authorization code, authorization URL `https://cliponit.app/oauth/authorize`, token URL `https://cliponit.app/oauth/token`, scopes: `clips`)

Synchronous (10 s – 2 min). Two stable faces (> 60 % of the time) → one `split` keyframe; otherwise `vertical` keyframes following the active speaker (`ease: smooth`); `horizontal` → full frame. Overwrites `layout` and `keyframes` of the edit for this orientation. Results are cached per clip bounds. 500 if the face model is missing on the server.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `orientation` 'vertical' | 'horizontal' | 'square' | 'portrait45': vertical = 9:16 1080x1920 (TikTok/Reels/Shorts), horizontal = 16:9 1920x1080 (YouTube), square = 1:1 1080x1080 (feed), portrait45 = 4:5 1080x1350 (Instagram feed). auto-reframe supports vertical|horizontal only.

## Response `200`

Reframe result

- object
  - `layout` 'vertical' | 'horizontal' | 'split' | 'trio' | 'spotlight' | 'centered', required: How source zones fill the output frame. `vertical`: 1 zone cropped to 9:16. `horizontal`: full frame (0 zones). `split`: 2 zones stacked (top, bottom). `trio`: 3 zones stacked. `spotlight`: 1 zone over a blurred full-frame background. `centered`: 1 square zone on a blue (#1e3a8a) background.
  - `keyframes` Keyframe[], required
    - `t` number, required
    - `layout` 'vertical' | 'horizontal' | 'split' | 'trio' | 'spotlight' | 'centered', required: How source zones fill the output frame. `vertical`: 1 zone cropped to 9:16. `horizontal`: full frame (0 zones). `split`: 2 zones stacked (top, bottom). `trio`: 3 zones stacked. `spotlight`: 1 zone over a blurred full-frame background. `centered`: 1 square zone on a blue (#1e3a8a) background.
    - `zones` Zone[], required
      - `x` number, required
      - `y` number, required
      - `w` number, required
      - `h` number, required
    - `ease` 'cut' | 'smooth' | '': `cut` = hard switch; `smooth` = zones glide from the previous keyframe over the 0.6 s before `t` (same layout only)
  - `faces` integer, required: Number of face tracks found
  - `speakers` integer, required: Number of stable speakers

## Other responses

- `404`: Resource not found or not owned by the user

---

[API](https://skmtc.dev/cliponit/apis/cliponit-api.md) · [All operations](https://skmtc.dev/cliponit/apis/cliponit-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cliponit/apis/cliponit-api/revisions/10e3e4327922?raw)