> ## 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 Transcription

> Generate accurate transcriptions from video and audio content

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

## Overview

Extract accurate transcriptions from your videos using AI-powered speech recognition. This endpoint generates timestamped transcriptions with support for multiple languages, translation, and script format options. Transcription output is available in multiple formats including SRT, VTT, CSV, and TXT.

## Rate Limiting

This endpoint is rate limited to 10 requests per minute per API key.

<Note>
  You must provide either `sourceUrl` or `uploadId`, but not both.
</Note>

## Video Requirements

<CardGroup cols={2}>
  <Card title="Duration" icon="clock">
    **Minimum:** 3 seconds\
    **Maximum:** 15 minutes
  </Card>

  <Card title="File Size" icon="scale-balanced">
    **Maximum:** 5 GB
  </Card>

  <Card title="Format" icon="file-video">
    MP4 or MOV with valid audio streams
  </Card>

  <Card title="Audio Quality" icon="microphone">
    Clear speech produces best transcription results
  </Card>
</CardGroup>

## Plan Limits

| Plan    | Concurrent Projects |
| ------- | ------------------- |
| Creator | 3                   |
| Studio  | 10                  |

Higher-tier plans allow you to process more videos simultaneously.

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

## Response

<ResponseField name="id" type="string">
  Unique project identifier
</ResponseField>

<ResponseField name="title" type="string">
  Project title (usually the filename)
</ResponseField>

<ResponseField name="thumbnail" type="string">
  Thumbnail URL for the project
</ResponseField>

<ResponseField name="billedDuration" type="number">
  Duration in seconds that will be billed to your account
</ResponseField>

<ResponseField name="status" type="string">
  Current processing status

  * `processing` - Audio is being transcribed
  * `completed` - Transcription has been generated successfully
  * `failed` - Processing failed due to an error
</ResponseField>

<ResponseField name="projectType" type="string">
  Type of project (always "transcription" for this endpoint)
</ResponseField>

<ResponseField name="source" type="string">
  Source of the video content

  * `Upload` - Uploaded file
  * `Youtube` - YouTube URL
  * `Generic` - External URL
</ResponseField>

<ResponseField name="language" type="string">
  Primary language of the video content
</ResponseField>

<ResponseField name="translateTranscription" type="boolean">
  Whether transcription will be translated
</ResponseField>

<ResponseField name="translationLanguages" type="array">
  Array of languages for translation
</ResponseField>

<ResponseField name="transcriptionScript" type="string">
  Script format for transcription ("native" or "roman")
</ResponseField>

<ResponseField name="metadata" type="object">
  Video file metadata including duration, resolution, format, etc.
</ResponseField>

<ResponseField name="urls" type="object">
  Project URLs and assets (populated when processing completes). Includes transcription files in multiple formats: SRT, VTT, CSV, and TXT.
</ResponseField>

<ResponseField name="createdAt" type="integer">
  Unix timestamp when the project was created
</ResponseField>

<ResponseField name="updatedAt" type="integer">
  Unix timestamp when the project was last updated
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL with Upload theme={"system"}
  curl -X POST "https://public.reap.video/api/v1/automation/create-transcription" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "uploadId": "65f1a2b3c4d5e6f7a8b9c0d1",
      "language": "en",
      "transcriptionScript": "native"
    }'
  ```

  ```bash cURL with URL theme={"system"}
  curl -X POST "https://public.reap.video/api/v1/automation/create-transcription" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sourceUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "language": "en"
    }'
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch('https://public.reap.video/api/v1/automation/create-transcription', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      uploadId: '65f1a2b3c4d5e6f7a8b9c0d1',
      language: 'en',
      transcriptionScript: 'native'
    })
  });

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

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

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

  data = {
      'uploadId': '65f1a2b3c4d5e6f7a8b9c0d1',
      'language': 'en',
      'transcriptionScript': 'native'
  }

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

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

  ```php PHP theme={"system"}
  <?php
  $data = [
      'uploadId' => '65f1a2b3c4d5e6f7a8b9c0d1',
      'language' => 'en',
      'transcriptionScript' => 'native'
  ];

  $ch = curl_init('https://public.reap.video/api/v1/automation/create-transcription');
  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 'Transcription 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-transcription"
      data := map[string]interface{}{
          "uploadId": "65f1a2b3c4d5e6f7a8b9c0d1",
          "language": "en",
          "transcriptionScript": "native",
      }
      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 CreateTranscriptionExample {
      public static void main(String[] args) throws Exception {
          URL url = new URL("https://public.reap.video/api/v1/automation/create-transcription");
          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\"," +
              "\"language\": \"en\"," +
              "\"transcriptionScript\": \"native\"}";
          try(OutputStream os = conn.getOutputStream()) {
              byte[] input = jsonInputString.getBytes("utf-8");
              os.write(input, 0, input.length);
          }
          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("Transcription project: " + response.toString());
      }
  }
  ```
</CodeGroup>

## Example Response

<CodeGroup>
  <CodeGroup.Tab label="200 OK">
    ```json theme={"system"}
    {
      "id": "65f1a2b3c4d5e6f7a8b9c0d2",
      "title": "my-video.mp4",
      "thumbnail": "https://cdn.reap.video/thumbnails/65f1a2b3c4d5e6f7a8b9c0d2.jpg",
      "billedDuration": 180.5,
      "status": "processing",
      "projectType": "transcription",
      "source": "Upload",
      "genre": "talking",
      "topics": [],
      "clipDurations": [],
      "selectedStart": 0,
      "selectedEnd": null,
      "reframeClips": false,
      "exportResolution": 720,
      "exportOrientation": "landscape",
      "captionsPreset": null,
      "enableCaptions": false,
      "enableEmojis": false,
      "enableHighlights": false,
      "language": "en",
      "dubbingLanguage": null,
      "translateTranscription": false,
      "translationLanguages": [],
      "transcriptionScript": "native",
      "metadata": {
        "duration": 180.5,
        "width": 1920,
        "height": 1080,
        "fps": 30,
        "bitrate": 5000000,
        "size": 45000000,
        "codec": "h264"
      },
      "urls": {},
      "createdAt": 1710000000,
      "updatedAt": 1710000000
    }
    ```
  </CodeGroup.Tab>

  <CodeGroup.Tab label="400 Bad Request">
    ```json theme={"system"}
    {
      "detail": "Missing source URL or upload ID."
    }
    ```
  </CodeGroup.Tab>

  <CodeGroup.Tab label="401 Unauthorized">
    ```json theme={"system"}
    {
      "detail": "Unauthorized - Invalid or missing API key"
    }
    ```
  </CodeGroup.Tab>

  <CodeGroup.Tab label="404 Not Found">
    ```json theme={"system"}
    {
      "detail": "Upload not found."
    }
    ```
  </CodeGroup.Tab>

  <CodeGroup.Tab label="429 Too Many Requests">
    ```json theme={"system"}
    {
      "detail": "Maximum concurrent projects reached. Please wait for the current projects to complete."
    }
    ```
  </CodeGroup.Tab>

  <CodeGroup.Tab label="500 Internal Server Error">
    ```json theme={"system"}
    {
      "detail": "Failed to create project. Please contact support."
    }
    ```
  </CodeGroup.Tab>
</CodeGroup>

## Processing Workflow

1. **Audio Extraction** - Audio is extracted from the video file
2. **Speech Recognition** - AI transcribes the speech with word-level timing
3. **Translation** - If a translation language is specified, the transcription is translated
4. **Format Generation** - Output is generated in multiple formats (SRT, VTT, CSV, TXT)
5. **Completion** - Use [Get Project Status](/api-reference/get-project-status) to monitor progress

## Output Formats

When transcription completes, the `urls` object in [Get Project Details](/api-reference/get-project-details) includes:

| Format | Field               | Description            |
| ------ | ------------------- | ---------------------- |
| SRT    | `transcription_srt` | SubRip subtitle format |
| VTT    | `transcription_vtt` | WebVTT subtitle format |
| CSV    | `transcription_csv` | Comma-separated values |
| TXT    | `transcription_txt` | Plain text transcript  |
| Audio  | `audioFile`         | Extracted audio file   |

## Best Practices

* **Audio Quality**: Clear audio with minimal background noise produces more accurate results
* **Language Selection**: Specify the language explicitly for better transcription accuracy
* **Script Format**: Use "roman" for romanized output of non-Latin script languages
* **Translation**: Combine with `translationLanguage` to get translated transcriptions

## Use Cases

<CardGroup cols={2}>
  <Card title="Content Indexing" icon="magnifying-glass">
    Generate searchable text from video libraries at scale
  </Card>

  <Card title="Subtitle Generation" icon="closed-captioning">
    Create SRT/VTT files for video players and platforms
  </Card>

  <Card title="Meeting Notes" icon="clipboard">
    Transcribe recorded meetings and webinars
  </Card>

  <Card title="Accessibility" icon="universal-access">
    Make video content accessible with accurate transcriptions
  </Card>
</CardGroup>

## Next Steps

After creating a transcription project:

1. Monitor progress with [Get Project Status](/api-reference/get-project-status)
2. Retrieve the full project with transcription URLs via [Get Project Details](/api-reference/get-project-details)
3. Download transcription files in your preferred format


## OpenAPI

````yaml POST /automation/create-transcription
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-transcription:
    post:
      summary: Create Transcription
      description: Generate accurate transcriptions from video and audio content
      operationId: createTranscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTranscriptionRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationProject'
components:
  schemas:
    CreateTranscriptionRequest:
      type: object
      properties:
        sourceUrl:
          type: string
          description: URL to a video or audio file (alternative to uploadId)
        uploadId:
          type: string
          description: Upload ID from a previously uploaded file (alternative to sourceUrl)
        language:
          type: string
          nullable: true
          description: >-
            Primary language of the video content (auto-detected if not
            provided)
        translationLanguage:
          type: string
          nullable: true
          description: Language to translate the transcription to
        transcriptionScript:
          type: string
          enum:
            - native
            - roman
          default: native
          description: Script format for transcription output
    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
        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
        selectedEnd:
          type: number
          nullable: true
        reframeClips:
          type: boolean
        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:
          type: object
        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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````