Feedback: api-reference-transcripts-get-subtitles

Documentation Feedback

Original URL: https://www.assemblyai.com/docs/api-reference/transcripts/get-subtitles
Category: api-reference
Generated: 05/08/2025, 4:31:09 pm

---

Claude Sonnet 4 Feedback

Generated: 05/08/2025, 4:31:08 pm

Technical Documentation Analysis: Get Subtitles for Transcript

Overall Assessment

This API documentation has significant gaps that would create friction for developers. While it covers the basic endpoint structure, it lacks essential details, contains errors, and provides poor examples.

Critical Issues to Address

1. Missing Information

Path Parameters - Incomplete Details

• subtitle_format: Only mentions it’s required but doesn’t specify valid values
• Fix: Add explicit list of supported formats

## Path Parameters

- **transcript_id** (string, required): The unique identifier of the transcript you want to export
  - Format: `transcript_xxxxxxxxxxxxxxxxxxxxxxxx`
- **subtitle_format** (string, required): The subtitle format to export
  - Valid values: `srt`, `vtt`
  - Example: `srt` for SubRip format, `vtt` for WebVTT format

Query Parameters - Insufficient Detail

• chars_per_caption: No guidance on valid ranges or behavior
• Fix: Add comprehensive parameter documentation

## Query Parameters

- **chars_per_caption** (integer, optional): Maximum characters per subtitle segment
  - Range: 1-1000
  - Default: 32 for SRT, 64 for VTT
  - Note: Setting to 0 uses format defaults
  - Example: `chars_per_caption=50`

Missing Response Documentation

• No success response examples
• No response headers information
• Fix: Add complete response documentation

## Response Body

### Success Response (200 OK)
Returns the subtitle file content as plain text in the requested format.

**Headers:**
- `Content-Type: text/plain; charset=utf-8`
- `Content-Disposition: attachment; filename="transcript_{id}.{format}"`

**Example SRT Response:**

1 00:00:00,000 —> 00:00:03,500 Welcome to our podcast about artificial intelligence.

2 00:00:03,500 —> 00:00:07,200 Today we’ll discuss the latest developments in machine learning.

**Example VTT Response:**

WEBVTT

00:00:00.000 —> 00:00:03.500 Welcome to our podcast about artificial intelligence.

00:00:03.500 —> 00:00:07.200 Today we’ll discuss the latest developments in machine learning.

2. Errors and Inconsistencies

Example Code Issues

• VTT example uses SRT endpoint (copy-paste error)
• Inconsistent parameter formatting (:transcript_id vs transcript_id)
• Excessive duplicate examples
• Fix: Correct and streamline examples

# Get SRT subtitles
curl "https://api.assemblyai.com/v2/transcript/64nygnr62k-405c-4ae8-8a6b-d90b40ff3f78/srt" \
  -H "Authorization: YOUR_API_KEY"

# Get VTT subtitles with custom character limit
curl "https://api.assemblyai.com/v2/transcript/64nygnr62k-405c-4ae8-8a6b-d90b40ff3f78/vtt?chars_per_caption=40" \
  -H "Authorization: YOUR_API_KEY"

3. Structure Improvements

Current structure lacks logical flow. Recommended reorganization:

# Get Subtitles for Transcript

Export your completed transcript as subtitle files (SRT or VTT) for use with video players, streaming platforms, or accessibility tools.

## Prerequisites
- A completed transcript (status must be `completed`)
- Valid API key with transcript access permissions

## Endpoint
```http
GET https://api.assemblyai.com/v2/transcript/{transcript_id}/{subtitle_format}

Parameters

[Detailed parameter documentation as shown above]

Usage Examples

[Clean, correct examples]

Response Format

[Complete response documentation]

Error Handling

[Detailed error scenarios]

Integration Examples

[Real-world usage patterns]

### 4. User Experience Enhancements

**Add Practical Context**
```markdown
## Common Use Cases
- **Video streaming**: Generate WebVTT files for HTML5 video players
- **Social media**: Create SRT files for platforms like YouTube or TikTok
- **Accessibility**: Provide closed captions for hearing-impaired users
- **Content localization**: Export subtitles as base for translation workflows

## Best Practices
- Use VTT format for web-based video players
- Use SRT format for traditional media players and editing software
- Set `chars_per_caption` between 32-42 for optimal readability
- Always verify transcript status is `completed` before requesting subtitles

Add Integration Guidance

## SDK Examples

### JavaScript
```javascript
const response = await fetch(
  `https://api.assemblyai.com/v2/transcript/${transcriptId}/srt?chars_per_caption=40`,
  {
    headers: {
      'Authorization': 'YOUR_API_KEY'
    }
  }
);
const subtitles = await response.text();

Python

import requests

response = requests.get(
    f"https://api.assemblyai.com/v2/transcript/{transcript_id}/vtt",
    headers={"Authorization": "YOUR_API_KEY"},
    params={"chars_per_caption": 40}
)
subtitles = response.text

### 5. Missing Error Handling Details

**Expand error documentation:**
```markdown
## Error Responses

| Status Code | Description | Common Causes |
|-------------|-------------|---------------|
| 400 | Bad Request | Invalid subtitle format, transcript_id format incorrect |
| 401 | Unauthorized | Missing or invalid API key |
| 404 | Not Found | Transcript doesn't exist or not accessible |
| 422 | Unprocessable Entity | Transcript not in `completed` status |
| 429 | Too Many Requests | Rate limit exceeded (see rate limiting docs) |
| 500 | Internal Server Error | Temporary server issue, retry after delay |

### Error Response Format
```json
{
  "error": "Transcript not found",
  "status": "error"
}

## Implementation Priority
1. **High**: Fix example errors and add response examples
2. **High**: Complete parameter documentation
3. **Medium**: Add SDK examples and use cases
4. **Medium**: Improve error handling documentation
5. **Low**: Add best practices and integration guidance

These improvements would transform this from basic reference material into comprehensive, developer-friendly documentation that reduces support burden and improves adoption.

---