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

# POST /v1/transcript — Get a Video Transcript

> Enqueue a transcription job and poll for the result. Supports native platform captions (1 credit) or AI Whisper transcription (5 credits).

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

```text theme={null}
POST https://api.veedcrawl.com/v1/transcript
```

This endpoint requires an `x-api-key` header and `Content-Type: application/json`.

### Body parameters

<ParamField body="url" type="string" required>
  The full public video URL, or a direct media file URL.
</ParamField>

<ParamField body="mode" type="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)
</ParamField>

<ParamField body="lang" type="string">
  Optional language hint for transcription — e.g. `"en"`, `"es"`, `"ur"`.
</ParamField>

### Example

```bash theme={null}
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

```json theme={null}
{
  "jobId": "job_abc123",
  "status": "queued"
}
```

***

## Step 2 — Poll for the result

```text theme={null}
GET https://api.veedcrawl.com/v1/transcript/{jobId}
```

### Example

```bash theme={null}
curl "https://api.veedcrawl.com/v1/transcript/job_abc123" \
  -H "x-api-key: YOUR_KEY"
```

### Response when complete

```json theme={null}
{
  "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" }
    ]
  }
}
```

<ResponseField name="resultJson.text" type="string">
  The full transcript as a single string.
</ResponseField>

<ResponseField name="resultJson.segments" type="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.
</ResponseField>

Poll until `status` is `"completed"` or `"failed"`. If the job fails, the response will include an error object describing what went wrong.

<Note>
  If you're using the Veedcrawl MCP server, polling is handled automatically. Your agent receives the finished transcript without writing any polling logic.
</Note>

<Tip>
  Use `mode="native"` for YouTube videos that have captions enabled. It's faster and costs only 1 credit instead of 5.
</Tip>