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

> Step 2 of 2 for transcribing your own file. Registers the object uploaded via /api/upload-url as a project and starts processing. Poll /api/detail/{id} or pass a webhookUrl.

Step 2 of 2 for transcribing your own file. Registers the object you uploaded via [Get Upload URL](https://docs.transcribetube.com/api-documentation/endpoint/post-apiuploadurl.md) as a project and starts processing. The response returns immediately; poll [Get Project](https://docs.transcribetube.com/api-documentation/endpoint/get-apidetail.md) or use a webhook — see [Lifecycle & Polling](https://docs.transcribetube.com/api-documentation/lifecycle.md).

## Request

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | Display name for the project. |
| `fileUrl` | string | yes | `https://videoven-data.s3.amazonaws.com/{key}::{key}` — the `key` from step 1, in both halves, separated by `::`. |
| `videoLength` | integer | yes | Duration in seconds. Used to reserve credit (1 credit per minute, minimum 1). |
| `language` | string | no | BCP-47 language code (`en`, `tr`, `de`, …). Defaults to auto-detect. |
| `webhookUrl` | string | no | HTTP(S) URL we POST to when transcription completes. |

Send `x-tt-source: <your-app>` if you want the project attributed to your integration in analytics; it defaults to `web`.

## Response

The created project. Its `state` starts at `upload` and advances to `transcription`, then `done`.

```json theme={null}
{
  "id": "f3c1e7a0-2b48-4a91-8a30-9b1c2d3e4f50",
  "state": "upload",
  "type": "FILEUPLOAD"
}
```

## Example

```bash cURL theme={null}
curl -X POST https://api.transcribetube.com/api/transcribeFile \
  -H "api-key: $TRANSCRIBETUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-tt-source: my-app" \
  -d "{
    \"name\": \"Weekly sync\",
    \"fileUrl\": \"https://videoven-data.s3.amazonaws.com/$KEY::$KEY\",
    \"videoLength\": 1830,
    \"language\": \"en\"
  }"
```


## OpenAPI

````yaml post /api/transcribeFile
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/transcribeFile:
    post:
      tags:
        - Api
      description: >-
        Step 2 of 2 for transcribing your own file. Registers the object
        uploaded via /api/upload-url as a project and starts processing. Poll
        /api/detail/{id} or pass a webhookUrl.
      operationId: ApiController_transcribeFile
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranscribeFileDto'
      responses:
        '201':
          description: Project created and queued for transcription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectDetailInProgress'
        '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'
      security:
        - api-key: []
components:
  schemas:
    TranscribeFileDto:
      type: object
      required:
        - name
        - fileUrl
        - videoLength
      properties:
        name:
          type: string
          description: Display name for the project
        fileUrl:
          type: string
          description: >-
            https://videoven-data.s3.amazonaws.com/{key}::{key}, using the key
            from /api/upload-url in both halves
        videoLength:
          type: integer
          description: Duration in seconds; used to reserve credit
        language:
          type: string
          description: Language code such as en or tr; defaults to auto-detect
        webhookUrl:
          type: string
          description: URL that receives a POST when transcription completes
    ProjectDetailInProgress:
      type: object
      description: Returned when state is 'upload' or 'transcription'
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        state:
          type: string
          enum:
            - upload
            - transcription
        message:
          type: string
          example: Transcription is in progress
        videoLength:
          type: integer
          description: Length in seconds
        createdAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: api-key

````

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