Skip to main content
POST
/
api
/
transcribeVideo
cURL
curl --request POST \
  --url https://api.transcribetube.com/api/transcribeVideo \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "language": "en",
  "webhookUrl": "http://example.com/webhook",
  "youtubeVideoId": "dQw4w9WgXcQ"
}
'
{
  "success": true,
  "projectId": "f3c1e7a0-2b48-4a91-8a30-9b1c2d3e4f50"
}
Submit a YouTube video for transcription. The request returns immediately with a projectId; the actual transcription runs in the background — see Lifecycle & Polling.

​
Request

FieldTypeRequiredDescription
youtubeVideoIdstringyesThe YouTube video ID (the v= parameter, e.g. dQw4w9WgXcQ).
webhookUrlstringyesHTTP(S) URL we POST to when transcription completes. See Webhooks.
languagestringnoBCP-47 language code (en, tr, de, …). Defaults to auto-detect.
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.

​
Examples

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"
  }'

​
Response

201 Created: 
{
  "success": true,
  "projectId": "f3c1e7a0-2b48-4a91-8a30-9b1c2d3e4f50"
}

​
Errors

StatusBodyWhen
400Validation erroryoutubeVideoId or webhookUrl missing/invalid.
401Missing api-keyHeader not provided or invalid.
402NOT_ENOUGH_CREDITSubscription has fewer credits than the video length requires.
404Video not foundYouTube 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.

Authorizations

​
api-key
string
header
required

Body

application/json
​
language
string
required

The language of the video

Example:

"en"

​
webhookUrl
string
required

The URL to send the transcription results to

Example:

"http://example.com/webhook"

​
youtubeVideoId
string
required

The ID of the YouTube video

Example:

"dQw4w9WgXcQ"

Response

Project created and queued for transcription

​
success
boolean
required
Example:

true

​
projectId
string<uuid>
required
Example:

"f3c1e7a0-2b48-4a91-8a30-9b1c2d3e4f50"