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

# Transcribe YouTube Video

> This API endpoint allows users to submit a YouTube video ID along with language preference and a webhook URL. Upon submission, the system processes the request and sends a POST request to the provided webhook URL with project details with transcription.

Submit a YouTube video for transcription. The request returns immediately with a `projectId`; the actual transcription runs in the background — see [Lifecycle & Polling](/api-documentation/lifecycle).

## Request

| Field            | Type   | Required | Description                                                                                       |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `youtubeVideoId` | string | yes      | The YouTube video ID (the `v=` parameter, e.g. `dQw4w9WgXcQ`).                                    |
| `webhookUrl`     | string | yes      | HTTP(S) URL we POST to when transcription completes. See [Webhooks](/api-documentation/webhooks). |
| `language`       | string | no       | BCP-47 language code (`en`, `tr`, `de`, …). Defaults to auto-detect.                              |

<Note>
  Credit is deducted at request time based on the video's reported length: **1 credit per minute (rounded down, minimum 1)**. If the YouTube video is unavailable or private, the request fails before any credit is consumed.
</Note>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.transcribetube.com/api/transcribeVideo \
    -H "api-key: $TRANSCRIBETUBE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "youtubeVideoId": "dQw4w9WgXcQ",
      "language": "en",
      "webhookUrl": "https://yourapp.com/hooks/transcribetube"
    }'
  ```

  ```js Node (fetch) theme={null}
  const res = await fetch("https://api.transcribetube.com/api/transcribeVideo", {
    method: "POST",
    headers: {
      "api-key": process.env.TRANSCRIBETUBE_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      youtubeVideoId: "dQw4w9WgXcQ",
      language: "en",
      webhookUrl: "https://yourapp.com/hooks/transcribetube",
    }),
  });
  const { projectId } = await res.json();
  ```

  ```python Python (requests) theme={null}
  import os, requests

  res = requests.post(
      "https://api.transcribetube.com/api/transcribeVideo",
      headers={"api-key": os.environ["TRANSCRIBETUBE_API_KEY"]},
      json={
          "youtubeVideoId": "dQw4w9WgXcQ",
          "language": "en",
          "webhookUrl": "https://yourapp.com/hooks/transcribetube",
      },
  )
  project_id = res.json()["projectId"]
  ```
</CodeGroup>

## Response

`201 Created`:

```json theme={null}
{
  "success": true,
  "projectId": "f3c1e7a0-2b48-4a91-8a30-9b1c2d3e4f50"
}
```

## Errors

| Status | Body                | When                                                                          |
| ------ | ------------------- | ----------------------------------------------------------------------------- |
| 400    | Validation error    | `youtubeVideoId` or `webhookUrl` missing/invalid.                             |
| 401    | `Missing api-key`   | Header not provided or invalid.                                               |
| 402    | `NOT_ENOUGH_CREDIT` | Subscription has fewer credits than the video length requires.                |
| 404    | Video not found     | YouTube returned no item for the supplied ID (private, deleted, or wrong ID). |

## What happens next

1. Project is created in `upload` state.
2. We download the video, then transcribe its audio.
3. State moves to `transcription`, then to `done`.
4. If you supplied `webhookUrl`, we POST the result to it. Either way, `GET /api/detail/{id}` will return the full transcription once state is `done`.


## OpenAPI

````yaml post /api/transcribeVideo
openapi: 3.0.0
info:
  title: Transcribe Tube
  description: Welcome to the API Panel for Transcribe Tube
  version: 0.0.1
  contact: {}
servers:
  - url: https://api.transcribetube.com
security: []
tags: []
paths:
  /api/transcribeVideo:
    post:
      tags:
        - Api
      description: >-
        This API endpoint allows users to submit a YouTube video ID along with
        language preference and a webhook URL. Upon submission, the system
        processes the request and sends a POST request to the provided webhook
        URL with project details with transcription.
      operationId: ApiController_transcribeVideo
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranscribeVideoDto'
      responses:
        '201':
          description: Project created and queued for transcription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscribeVideoResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid api-key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Not enough credit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: YouTube video not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - api-key: []
components:
  schemas:
    TranscribeVideoDto:
      type: object
      properties:
        language:
          type: string
          description: The language of the video
          example: en
        webhookUrl:
          type: string
          description: The URL to send the transcription results to
          example: http://example.com/webhook
        youtubeVideoId:
          type: string
          description: The ID of the YouTube video
          example: dQw4w9WgXcQ
          default: null
      required:
        - language
        - webhookUrl
        - youtubeVideoId
    TranscribeVideoResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        projectId:
          type: string
          format: uuid
          example: f3c1e7a0-2b48-4a91-8a30-9b1c2d3e4f50
      required:
        - success
        - projectId
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: api-key

````