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

# Extract Transcript

> Extract audio-visual transcript with timestamps and speaker diarization

## POST /api/v1/transcript

Extract audio-visual transcript from video with word-level timestamps and optional speaker diarization. Returns both structured segments and full text.

### Parameters

| Parameter           | Type    | Required | Description                                   |
| ------------------- | ------- | -------- | --------------------------------------------- |
| video\_url          | URL     | Yes      | URL to the video to transcribe                |
| include\_speakers   | boolean | No       | Include speaker diarization (default: false)  |
| include\_timestamps | boolean | No       | Include word-level timestamps (default: true) |

### Response

| Field         | Description                                  |
| ------------- | -------------------------------------------- |
| transcript    | Array of transcript segments with timestamps |
| full\_text    | Complete transcript as plain text            |
| duration\_sec | Duration of the video in seconds             |

### Transcript Segment Object

| Field            | Description                                           |
| ---------------- | ----------------------------------------------------- |
| text             | Transcript text for this segment                      |
| start\_time\_sec | Start time of the segment in seconds                  |
| end\_time\_sec   | End time of the segment in seconds                    |
| speaker          | Speaker identifier (only when include\_speakers=true) |

### Example Request

```bash theme={null}
curl -X POST https://api.usenarrative.ai/api/v1/transcript \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/interview.mp4",
    "include_speakers": true,
    "include_timestamps": true
  }'
```

### Example Response

```json theme={null}
{
  "transcript": [
    {
      "text": "Welcome to the show. Today we have a special guest.",
      "start_time_sec": 0.5,
      "end_time_sec": 3.2,
      "speaker": "Speaker 1"
    },
    {
      "text": "Thanks for having me. I'm excited to be here.",
      "start_time_sec": 3.5,
      "end_time_sec": 5.8,
      "speaker": "Speaker 2"
    },
    {
      "text": "Let's dive right in. Tell us about your latest project.",
      "start_time_sec": 6.1,
      "end_time_sec": 8.9,
      "speaker": "Speaker 1"
    }
  ],
  "full_text": "Welcome to the show. Today we have a special guest. Thanks for having me. I'm excited to be here. Let's dive right in. Tell us about your latest project.",
  "duration_sec": 3600
}
```

### Notes

* Transcription uses state-of-the-art speech recognition
* Speaker diarization identifies unique speakers (Speaker 1, Speaker 2, etc.)
* Timestamps are precise to the hundredth of a second
* The `full_text` field provides the complete transcript without timestamps
* Supports multiple languages (auto-detected)


## OpenAPI

````yaml POST /api/v1/transcript
openapi: 3.0.3
info:
  title: Hooks API
  description: AI-powered social media hook generation and video analysis
  version: 1.0.0
servers:
  - url: https://api.usenarrative.ai
    description: Production
security: []
paths:
  /api/v1/transcript:
    post:
      tags:
        - Analysis
      summary: Extract Transcript
      description: >-
        Extract audio-visual transcript from video with word-level timestamps
        and optional speaker diarization.
      operationId: extractTranscript
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractTranscriptRequest'
      responses:
        '200':
          description: Transcript extracted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractTranscriptResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ExtractTranscriptRequest:
      type: object
      properties:
        video_url:
          type: string
          format: uri
          description: URL to the video to transcribe
          example: https://example.com/video.mp4
        include_speakers:
          type: boolean
          description: Include speaker diarization
          default: false
          example: true
        include_timestamps:
          type: boolean
          description: Include word-level timestamps
          default: true
          example: true
      required:
        - video_url
    ExtractTranscriptResponse:
      type: object
      properties:
        transcript:
          type: array
          items:
            $ref: '#/components/schemas/TranscriptSegment'
          description: Array of transcript segments with timestamps
        full_text:
          type: string
          description: Complete transcript as plain text
          example: Welcome to the game. Today we have an exciting matchup...
        duration_sec:
          type: number
          description: Duration of the video in seconds
          example: 3600
      required:
        - transcript
        - full_text
        - duration_sec
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
          example: Invalid video URL provided
    TranscriptSegment:
      type: object
      properties:
        text:
          type: string
          description: Transcript text for this segment
          example: Welcome to the game.
        start_time_sec:
          type: number
          description: Start time of the segment in seconds
          example: 0.5
        end_time_sec:
          type: number
          description: End time of the segment in seconds
          example: 2.1
        speaker:
          type: string
          description: Speaker identifier (only present when include_speakers=true)
          example: Speaker 1
      required:
        - text
        - start_time_sec
        - end_time_sec

````