Skip to main content
Transcription is an async operation. You POST to /v1/transcript to enqueue the job and receive a jobId, then poll GET /v1/transcript/{jobId} until the status reaches "completed" or "failed". The MCP server handles polling automatically if you’re using it via an AI agent. Credits: 1 credit for native platform captions, 5 credits for Whisper AI transcription.

​
Step 1 — Enqueue the job

POST https://api.veedcrawl.com/v1/transcript
This endpoint requires an x-api-key header and Content-Type: application/json.

​
Body parameters

​
url
string
required
The full public video URL, or a direct media file URL.
​
mode
string
How to generate the transcript. Options:
  • "native" — use the platform’s own captions (1 credit)
  • "generate" — use Whisper AI transcription (5 credits)
  • "auto" — try native captions first, fall back to Whisper if unavailable (default)
​
lang
string
Optional language hint for transcription — e.g. "en", "es", "ur".

​
Example

curl -X POST "https://api.veedcrawl.com/v1/transcript" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "mode": "auto"}'

​
Response

{
  "jobId": "job_abc123",
  "status": "queued"
}

​
Step 2 — Poll for the result

GET https://api.veedcrawl.com/v1/transcript/{jobId}

​
Example

curl "https://api.veedcrawl.com/v1/transcript/job_abc123" \
  -H "x-api-key: YOUR_KEY"

​
Response when complete

{
  "jobId": "job_abc123",
  "status": "completed",
  "resultJson": {
    "text": "Never gonna give you up, never gonna let you down...",
    "segments": [
      { "start": 0.0, "end": 3.5, "text": "Never gonna give you up" },
      { "start": 3.5, "end": 7.2, "text": "never gonna let you down" }
    ]
  }
}
​
resultJson.text
string
The full transcript as a single string.
​
resultJson.segments
array
Array of timestamped segments. Each segment has start (seconds), end (seconds), and text (the spoken content in that interval). Use segments to build search indexes, highlight spoken text, or align transcript content to specific moments in the video.
Poll until status is "completed" or "failed". If the job fails, the response will include an error object describing what went wrong.
If you’re using the Veedcrawl MCP server, polling is handled automatically. Your agent receives the finished transcript without writing any polling logic.
Use mode="native" for YouTube videos that have captions enabled. It’s faster and costs only 1 credit instead of 5.