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

# Create Reframe

> Automatically reframe videos for different aspect ratios

> **For AI agents:** a documentation index is at [/llms.txt](https://docs.reap.video/llms.txt). Every page is also available as markdown, just append `.md` to the URL.

## Overview

Automatically reframe videos from landscape to portrait or square formats using AI. Perfect for adapting content for TikTok, Instagram Stories, and other vertical video platforms.

You must provide either `sourceUrl` (a web video URL, e.g. YouTube) or `uploadId` (a previously uploaded file), but not both. Use `selectedStart` / `selectedEnd` to reframe just a window of a longer video — only the selected window is billed.

## Rate Limiting

This endpoint allows **10 requests per minute per API key**. Each endpoint has its own budget, so this allowance is not shared with the rest of the API — see [Rate limiting](https://docs.reap.video/api-reference/2_authentication.md#rate-limiting).

## Video Requirements

> [card] Selection Window
>
> **Minimum:** 3 seconds\
> **Maximum:** 10 minutes, or 30 minutes on a monthly or yearly Studio plan\
> The source video itself can be longer — select a window with `selectedStart` / `selectedEnd`.

> [card] File Size
>
> **Maximum:** 2 GB, or 5 GB on a monthly or yearly Studio plan (uploads)

> [card] Format
>
> MP4 or MOV with valid video streams, or a supported web URL

> [card] Source Format
>
> Landscape source videos only — portrait sources are rejected (URL sources after download, with the charge refunded)

## Plan Limits

> [!WARNING]
>
> Reframe is available on **Creator** and **Studio** plans. Free plans cannot use this endpoint.

| Plan | Concurrent Projects | Max Resolution | Max Selection Window | Max Upload Size |
| - | - | - | - | - |
| Creator | 3 | 1080p | 10 minutes | 2 GB |
| Studio | 10 | 4K (2160p) | 30 minutes | 5 GB |

The 30-minute window and 5 GB upload cap apply to Studio subscriptions billed through Stripe. AppSumo Studio tiers keep the 10-minute / 2 GB limits.

> [!NOTE]
>
> The Automation API requires an active paid subscription. [View pricing](https://reap.video/pricing) to compare plans.

## Response

**id** `string`

Unique project identifier

**title** `string`

Project title (usually the filename)

**thumbnail** `string`

Thumbnail URL for the project

**billedDuration** `number`

Minutes billed to your account: the processed part, rounded to the nearest minute (at least 1)

**status** `string`

Current processing status

* `processing` - Video is being analyzed and reframed
* `completed` - Reframing completed successfully
* `failed` - Processing failed due to an error

**projectType** `string`

Type of project (always "reframe" for this endpoint)

**source** `string`

Source of the video content, e.g. "Upload" or "Youtube"

**genre** `string`

Video genre used for AI analysis

**topics** `array`

Array of identified topics in the video

**clipDurations** `array`

Array of clip duration preferences

**selectedStart** `number`

Start time in seconds for processing (null if entire video)

**selectedEnd** `number`

End time in seconds for processing (null if entire video)

**exportResolution** `integer`

Output resolution for the reframed video

**exportOrientation** `string`

Output orientation for the reframed video

**captionsPreset** `string`

Caption style preset ID (null if captions disabled)

**enableCaptions** `boolean`

Whether captions are enabled

**enableEmojis** `boolean`

Whether emojis are added to captions

**enableHighlights** `boolean`

Whether keyword highlighting is enabled

**language** `string`

Primary language of the video content

**dubbingLanguage** `string`

Target dubbing language (null if not applicable)

**translateTranscription** `boolean`

Whether transcription will be translated

**translationLanguages** `array`

Array of languages for translation

**metadata** `object`

Video file metadata including duration, resolution, format, etc.

**urls** `object`

Project URLs and assets (populated when processing completes)

**createdAt** `integer`

Unix timestamp when the project was created

**updatedAt** `integer`

Unix timestamp when the project was last updated

## Example Request

```bash cURL theme={"system"}
curl -X POST "https://public.reap.video/api/v1/automation/create-reframe" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "65f1a2b3c4d5e6f7a8b9c0d1",
    "genre": "talking",
    "orientation": "portrait",
    "disableAutoSplit": false
  }'
```

```javascript JavaScript theme={"system"}
const response = await fetch('https://public.reap.video/api/v1/automation/create-reframe', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uploadId: '65f1a2b3c4d5e6f7a8b9c0d1',
    genre: 'talking',
    orientation: 'portrait',
    disableAutoSplit: false
  })
});

const project = await response.json();
console.log('Reframe project created:', project.id);
```

```python Python theme={"system"}
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    'uploadId': '65f1a2b3c4d5e6f7a8b9c0d1',
    'genre': 'talking',
    'orientation': 'square',
    'disableAutoSplit': False
}

response = requests.post(
    'https://public.reap.video/api/v1/automation/create-reframe',
    headers=headers,
    json=data
)

project = response.json()
print(f'Reframe project created: {project["id"]}')
```

```php PHP theme={"system"}
<?php
$data = [
    'uploadId' => '65f1a2b3c4d5e6f7a8b9c0d1',
    'genre' => 'talking',
    'orientation' => 'portrait',
    'disableAutoSplit' => false
];

$ch = curl_init('https://public.reap.video/api/v1/automation/create-reframe');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$project = json_decode($response, true);
echo 'Reframe project created: ' . $project['id'] . "\n";
?>
```

```go Go theme={"system"}
package main
import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)
func main() {
    url := "https://public.reap.video/api/v1/automation/create-reframe"
    data := map[string]interface{}{
        "uploadId": "65f1a2b3c4d5e6f7a8b9c0d1",
        "genre": "talking",
        "orientation": "portrait",
        "disableAutoSplit": false,
    }
    payload, _ := json.Marshal(data)
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

```java Java theme={"system"}
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
public class CreateReframeExample {
    public static void main(String[] args) throws Exception {
        URL url = new URL("https://public.reap.video/api/v1/automation/create-reframe");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Authorization", "Bearer YOUR_API_KEY");
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setDoOutput(true);
        String jsonInputString = "{\"uploadId\":\"65f1a2b3c4d5e6f7a8b9c0d1\",\"genre\":\"talking\",\"orientation\":\"portrait\",\"disableAutoSplit\":false}";
        try (OutputStream os = conn.getOutputStream()) {
            os.write(jsonInputString.getBytes("utf-8"));
        }
        BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), "utf-8"));
        StringBuilder response = new StringBuilder();
        String responseLine;
        while ((responseLine = br.readLine()) != null) {
            response.append(responseLine.trim());
        }
        System.out.println("Reframe project created: " + response.toString());
    }
}
```

## Example Response

**200 OK**

```json theme={"system"}
{
  "id": "65f1a2b3c4d5e6f7a8b9c0d6",
  "title": "Landscape Video Reframe",
  "thumbnail": "https://cdn.reap.video/thumbnails/65f1a2b3c4d5e6f7a8b9c0d6.jpg",
  "billedDuration": 10,
  "status": "processing",
  "projectType": "reframe",
  "source": "Upload",
  "genre": "talking",
  "topics": [],
  "clipDurations": [],
  "selectedStart": 0,
  "selectedEnd": null,
  "exportResolution": 1080,
  "exportOrientation": "portrait",
  "captionsPreset": null,
  "enableCaptions": false,
  "enableEmojis": false,
  "enableHighlights": false,
  "language": "en",
  "dubbingLanguage": null,
  "translateTranscription": false,
  "translationLanguages": [],
  "transcriptionScript": "native",
  "metadata": {
    "duration": 600.0,
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "bitrate": 4000000,
    "size": 120000000,
    "codec": "h264"
  },
  "urls": {},
  "createdAt": 1710003000,
  "updatedAt": 1710003000
}
```

**400 Bad Request**

```json theme={"system"}
{
  "detail": "Missing required parameter: uploadId"
}
```

**401 Unauthorized**

```json theme={"system"}
{
  "detail": "Unauthorized - Invalid or missing API key"
}
```

**404 Not Found**

```json theme={"system"}
{
  "detail": "Upload not found"
}
```

**422 Unprocessable Entity**

```json theme={"system"}
{
  "detail": "Please select a range up to 10 minutes from the timeline."
}
```

**429 Too Many Requests**

```json theme={"system"}
{
  "error": "Rate limit exceeded: 10 per 1 minute"
}
```

**429 Concurrent Project Limit**

```json theme={"system"}
{
  "detail": "Maximum concurrent projects reached. Please wait for the current projects to complete."
}
```

**500 Internal Server Error**

```json theme={"system"}
{
  "detail": "Internal Server Error - Something went wrong on our end"
}
```

## Processing Workflow

1. **Upload Analysis** - Video is analyzed for speakers, objects, and key visual elements
2. **Smart Cropping** - AI automatically crops and reframes to keep important content in view
3. **Motion Tracking** - Follows speakers and maintains optimal framing throughout the video
4. **Segmentation** - Optionally splits longer videos into optimal segments (unless disabled)
5. **Output Generation** - Creates reframed video in the target aspect ratio

## Reframing Features

* **Speaker Tracking**: Automatically follows speakers and keeps them centered
* **Object Recognition**: Identifies and tracks important visual elements
* **Smart Cropping**: Maintains optimal composition throughout the video
* **Smooth Transitions**: Ensures natural camera movements between focus points
* **Auto-Segmentation**: Intelligently splits content into engaging segments

## Use Cases

> [card] Multi-Platform Distribution
>
> Automatically adapt content for YouTube, TikTok, Instagram, and more

> [card] Content Management Systems
>
> Generate all aspect ratio variants on upload for any platform

> [card] Video Hosting Platforms
>
> Offer automatic reframing as a feature to your users

> [card] Marketing Automation
>
> Scale ad creative production across different placements

## Best Practices

* **Source Quality**: Use high-resolution landscape videos for best results
* **Speaker Positioning**: Videos with centered speakers reframe more effectively
* **Content Type**: Works best with talking head videos and presentations
* **Duration**: Shorter videos (under 5 minutes) process faster and more accurately


## OpenAPI

````yaml POST /automation/create-reframe
openapi: 3.1.0
info:
  title: Reap Automation API
  description: AI-powered video processing automation API
  version: 1.0.0
servers:
  - url: https://public.reap.video/api/v1
security:
  - bearerAuth: []
paths:
  /automation/create-reframe:
    post:
      summary: Create Reframe
      description: Automatically reframe videos for different aspect ratios
      operationId: createReframe
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReframeRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationProject'
components:
  schemas:
    CreateReframeRequest:
      type: object
      properties:
        sourceUrl:
          type: string
          description: Video URL to process, e.g. a YouTube link (alternative to uploadId)
        uploadId:
          type: string
          description: Upload ID from a previously uploaded file (alternative to sourceUrl)
        genre:
          type: string
          enum:
            - talking
            - screenshare
            - gaming
          default: talking
          description: Video genre for better AI analysis
        orientation:
          type: string
          enum:
            - portrait
            - square
          default: portrait
          description: Target orientation
        exportResolution:
          type: integer
          enum:
            - 720
            - 1080
            - 1440
            - 2160
          default: 1080
          description: >-
            Output resolution for the reframed video. Resolutions above 1080
            require a Studio plan. Capped at the source's actual resolution.
        selectedStart:
          type: number
          nullable: true
          description: >-
            Start time in seconds of the window to reframe (defaults to the
            start of the video)
          minimum: 0
        selectedEnd:
          type: number
          nullable: true
          description: >-
            End time in seconds of the window to reframe (defaults to the end of
            the video). The selected window must be between 3 seconds and 10
            minutes; only the window is billed.
          minimum: 0
        disableAutoSplit:
          type: boolean
          default: false
          description: Whether to disable automatic splitting into segments
    AutomationProject:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        thumbnail:
          type: string
        billedDuration:
          type: number
        status:
          type: string
          enum:
            - queued
            - prepped
            - draft
            - processing
            - finalizing
            - completed
            - invalid
            - expired
            - failed
            - error
        projectType:
          type: string
          enum:
            - clipping
            - captions
            - reframe
            - dubbing
            - transcription
            - editor
        source:
          type: string
          enum:
            - Upload
            - Youtube
            - Vimeo
            - TwitchVod
            - Twitter
            - RumbleEmbed
            - Generic
        genre:
          $ref: '#/components/schemas/VideoGenre'
        topics:
          type: array
          items:
            type: string
        clipDurations:
          type: array
          items:
            type: array
            items:
              type: integer
        selectedStart:
          type: number
          nullable: true
          minimum: 0
        selectedEnd:
          type: number
          nullable: true
          minimum: 0
        exportResolution:
          type: integer
        exportOrientation:
          $ref: '#/components/schemas/VideoOrientation'
        captionsPreset:
          type: string
          nullable: true
        enableCaptions:
          type: boolean
        enableEmojis:
          type: boolean
        enableHighlights:
          type: boolean
        language:
          type: string
          nullable: true
        dubbingLanguage:
          type: string
          nullable: true
        translateTranscription:
          type: boolean
        translationLanguages:
          type: array
          items:
            type: string
        transcriptionScript:
          $ref: '#/components/schemas/TranscriptionScript'
        metadata:
          $ref: '#/components/schemas/VideoFileMeta'
        urls:
          $ref: '#/components/schemas/ProjectUrls'
        createdAt:
          type: integer
        updatedAt:
          type: integer
    VideoGenre:
      type: string
      enum:
        - talking
        - screenshare
        - gaming
      default: talking
    VideoOrientation:
      type: string
      enum:
        - landscape
        - portrait
        - square
    TranscriptionScript:
      type: string
      enum:
        - native
        - roman
      default: native
    VideoFileMeta:
      type: object
      properties:
        width:
          type: integer
        height:
          type: integer
        aspectRatio:
          type: string
        size:
          type: number
        bitrate:
          type: number
        fps:
          type: number
        duration:
          type: number
        rotation:
          type: integer
        resolution:
          type: integer
        codec:
          type: string
        codecFullName:
          type: string
        codecTag:
          type: string
        format:
          type: string
        formatFullName:
          type: string
    ProjectUrls:
      type: object
      description: >-
        Presigned URLs for the project's assets. URLs expire — always use the
        most recent API response. The transcription_* subtitle/text exports are
        only present on transcription projects.
      properties:
        videoFile:
          type: string
          description: Presigned URL of the processed source video
        audioFile:
          type: string
          description: Presigned URL of the extracted audio track
        transcription:
          type: string
          description: >-
            Presigned URL of the word-level transcript JSON (the translated
            version when translation ran). Lets API consumers audit content
            without video playback.
        transcription_srt:
          type: string
          description: SRT subtitles — transcription projects only
        transcription_vtt:
          type: string
          description: WebVTT subtitles — transcription projects only
        transcription_csv:
          type: string
          description: CSV transcript — transcription projects only
        transcription_txt:
          type: string
          description: Plain-text transcript — transcription projects only
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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