---
title: "Get the transcript of a video | GPT-Video API reference"
description: "Returns the words of a video with their times, as speech recognition heard them."
url: "https://www.gpt-video.com/developers/api/get-transcript"
operation: "get_transcript"
method: "GET"
path: "/v1/assets/{assetId}/transcript"
scope: "clips:read"
---

Do not assume endpoints have parameters other than the ones explicitly specified.

# Get the transcript of a video

Operation id `get_transcript`. Request `GET /v1/assets/{assetId}/transcript`.

Returns the words of a video with their times, as speech recognition heard them.

Beta. This endpoint is supported and can gain new fields. If a change would break your code, we tell you before it takes effect and list it in the changelog.

## About

A video is transcribed when a project that uses it as its source is analyzed, and the transcript is kept afterwards. This is the raw transcript: corrections made in the GPT-Video editor are not in it. While the analysis that makes it is running the answer is NOT_READY, and a video that no analysis has used answers CONFLICT.

## Example use

A team that keeps a written version of every interview reads the transcript of each analyzed video and saves it next to the recording. A search tool then uses the word times to link a sentence to the moment it was said.

## Endpoint

```text
GET https://api.gpt-video.com/v1/assets/{assetId}/transcript
```

- Scope `clips:read`.
- Rate limit 120 requests a minute for each key and 240 for each account, shared by every `read` call. See [rate limits](/developers/rate-limits.md).
- No `Idempotency-Key`.

## Parameters

### Path

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `assetId` | string | Required | The id of the asset. It starts with ast_, or with ast_n for the converted copy an analysis makes. Matches `^ast_n?[0-9a-f]{20}$`. |

### Query

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `words` | boolean | Optional | false leaves out the list of words and returns the segments alone, which is much shorter; words is then an empty list. Defaults to true. |

## Request

Read the transcript of a video.

```bash title="curl"
curl "https://api.gpt-video.com/v1/assets/ast_3f9a1c7e5b2d4086a1c4/transcript" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"
```

```ts title="TypeScript"
const res = await fetch("https://api.gpt-video.com/v1/assets/ast_3f9a1c7e5b2d4086a1c4/transcript", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);
```

```python title="Python"
import os

import requests

r = requests.get(
    "https://api.gpt-video.com/v1/assets/ast_3f9a1c7e5b2d4086a1c4/transcript",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)
```

```json title="MCP (Full)"
{
  "method": "tools/call",
  "params": {
    "name": "get_transcript",
    "arguments": {
      "assetId": "ast_3f9a1c7e5b2d4086a1c4"
    }
  }
}
```

## Response

A successful call answers HTTP 200.

### Response example

```json title="HTTP 200"
{
  "transcript": {
    "assetId": "ast_3f9a1c7e5b2d4086a1c4",
    "language": "en",
    "createdAt": "2026-09-01T09:20:00.000Z",
    "words": [
      {
        "text": "the",
        "startSec": 118,
        "endSec": 118.35,
        "confidence": 0.94
      },
      {
        "text": "first",
        "startSec": 118.4,
        "endSec": 118.75,
        "confidence": 0.94
      },
      {
        "text": "customer",
        "startSec": 118.8,
        "endSec": 119.15,
        "confidence": 0.94
      }
    ],
    "segments": [
      {
        "startSec": 118,
        "endSec": 152,
        "text": "the first customer paid us before we had a product"
      }
    ]
  }
}
```

**All response fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `transcript` | object | Required |   |
| `transcript.assetId` | string | Required | The asset that was asked for. |
| `transcript.language` | string | Required | The language of the speech, as a two-letter code such as en. |
| `transcript.createdAt` | string | Required | An ISO 8601 time in UTC. |
| `transcript.words` | array of objects | Required | Every word, in the order it is spoken. |
| `transcript.segments` | array of objects | Required | The words grouped into stretches of speech. |

**Fields of transcript.words[]**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `transcript.words[].text` | string | Required |   |
| `transcript.words[].startSec` | number | Required | When the word starts, in seconds from the start of the video. |
| `transcript.words[].endSec` | number | Required | When the word ends, in seconds from the start of the video. |
| `transcript.words[].confidence` | number or null | Required | How sure the recognition is of this word, from 0 to 1; null when it did not say. |

**Fields of transcript.segments[]**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `transcript.segments[].startSec` | number | Required |   |
| `transcript.segments[].endSec` | number | Required |   |
| `transcript.segments[].text` | string | Required |   |

**More examples**

#### Read the transcript of a video no analysis has used

`GET /v1/assets/ast_8e21b0d94c6f4a17b358/transcript`

```json title="HTTP 409"
{
  "error": {
    "code": "CONFLICT",
    "message": "This video has not been transcribed yet. Analyze a project that uses it as its source; the transcript is kept when the analysis finishes.",
    "requestId": "req_0d6a2e8c4f1b7d3a9e5c2f6b"
  }
}
```

#### Read the transcript while the analysis is running

`GET /v1/assets/ast_8e21b0d94c6f4a17b358/transcript`

- `Retry-After: 10`

```json title="HTTP 409"
{
  "error": {
    "code": "NOT_READY",
    "message": "The transcript of this video is still being made.",
    "hint": "Wait the number of seconds in the Retry-After header, then send the same request again.",
    "requestId": "req_7b3e9c1f5a0d4b8e2c6f9a3d"
  }
}
```

#### Read the transcript of an asset that does not exist

`GET /v1/assets/ast_0b1e5c9d3a7f40628e2d/transcript`

```json title="HTTP 404"
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Asset ast_0b1e5c9d3a7f40628e2d not found",
    "hint": "Check the id. An id that belongs to another account is not found either.",
    "requestId": "req_9e5a1c7f3b0d6e2a8c4f1b5d"
  }
}
```

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| [`NOT_FOUND`](/developers/errors.md#NOT_FOUND) | 404 | Read the transcript of an asset that does not exist | Change the request, then send it again. |
| [`CONFLICT`](/developers/errors.md#CONFLICT) | 409 | Read the transcript of a video no analysis has used | Read the resource again, then decide. Do not send the same request again. |
| [`NOT_READY`](/developers/errors.md#NOT_READY) | 409 | Read the transcript while the analysis is running | Wait for Retry-After, then send the same request again. |

Every call can also answer these errors. [`VALIDATION_FAILED`](/developers/errors.md#VALIDATION_FAILED), [`UNKNOWN_PARAMETER`](/developers/errors.md#UNKNOWN_PARAMETER), [`UNAUTHORIZED`](/developers/errors.md#UNAUTHORIZED), [`SCOPE_MISSING`](/developers/errors.md#SCOPE_MISSING), [`RATE_LIMITED`](/developers/errors.md#RATE_LIMITED), [`INTERNAL`](/developers/errors.md#INTERNAL), [`UNAVAILABLE`](/developers/errors.md#UNAVAILABLE).

## Cost

No credits are used.

## Related operations

- [`get_asset`](/developers/api/get-asset.md) (`GET /v1/assets/{assetId}`) Get an asset
- [`list_assets`](/developers/api/list-assets.md) (`GET /v1/assets`) List your videos
- [`analyze_project`](/developers/api/analyze-project.md) (`POST /v1/projects/{projectId}/analyze`) Analyze a project

## Questions

### Why are my corrections from the editor missing?

This is the transcript as speech recognition produced it. Corrections made in the editor belong to a composition and change only its captions. This transcript stays as it was.

### How do I get a transcript for a video?

Create a project with the video as its source and analyze it. The transcript is made during the analysis and stays with the video.