Feedback: api-reference-lemur-summary

Documentation Feedback

Original URL: https://www.assemblyai.com/docs/api-reference/lemur/summary
Category: api-reference
Generated: 05/08/2025, 4:32:17 pm

---

Claude Sonnet 4 Feedback

Generated: 05/08/2025, 4:32:16 pm

Technical Documentation Analysis: LeMUR Summary API

Critical Issues Requiring Immediate Attention

1. Missing Request Body Documentation

Problem: No formal specification of request parameters Impact: Users cannot understand what fields are available, required, or optional

Action Required:

## Request Body Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `final_model` | string | Yes | The AI model to use (e.g., "anthropic/claude-sonnet-4-20250514") |
| `transcript_ids` | array[string] | Yes* | Array of transcript IDs to summarize |
| `context` | string | No | Additional context to guide the summary |
| `max_output_size` | integer | No | Maximum length of summary in characters (default: 3000) |
| `temperature` | number | No | Controls randomness (0-1, default: 0) |

*Either `transcript_ids` or direct transcript text is required

2. Completely Missing Response Documentation

Problem: No response body schema, examples, or field descriptions Impact: Users don’t know what to expect in successful responses

Action Required:

## Response Schema

### Success Response (200)
```json
{
  "request_id": "string",
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 567
  },
  "response": "Generated summary text..."
}

Error Response Examples

{
  "error": "Invalid transcript_id",
  "message": "Transcript 47b95ba5-8889-44d8-bc80-5de38306e582 not found"
}

### 3. **Redundant and Useless Examples**
**Problem**: 7 identical examples that provide no educational value
**Impact**: Clutters documentation and wastes user time

**Action Required**: Replace with diverse, meaningful examples:

```markdown
## Examples

### Basic Summary
```shell
curl -X POST https://api.assemblyai.com/lemur/v3/generate/summary \
     -H "Authorization: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "final_model": "anthropic/claude-sonnet-4-20250514",
       "transcript_ids": ["47b95ba5-8889-44d8-bc80-5de38306e582"]
     }'

Summary with Context and Constraints

curl -X POST https://api.assemblyai.com/lemur/v3/generate/summary \
     -H "Authorization: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "final_model": "anthropic/claude-sonnet-4-20250514",
       "transcript_ids": ["47b95ba5-8889-44d8-bc80-5de38306e582"],
       "context": "Focus on key business decisions and action items from this board meeting",
       "max_output_size": 500,
       "temperature": 0.2
     }'

Multiple Transcripts

curl -X POST https://api.assemblyai.com/lemur/v3/generate/summary \
     -H "Authorization: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "final_model": "anthropic/claude-sonnet-4-20250514",
       "transcript_ids": [
         "47b95ba5-8889-44d8-bc80-5de38306e582",
         "8c2d3e4f-1234-5678-9abc-def012345678"
       ],
       "context": "Combine insights from both customer interviews"
     }'

## Missing Essential Information

### 4. **Prerequisites and Setup**
Add a prerequisites section:
```markdown
## Before You Start

1. **Get your API key** from the [AssemblyAI Dashboard](https://www.assemblyai.com/app/)
2. **Upload and transcribe your audio** using the [Transcription API](../transcription)
3. **Note your transcript ID(s)** from the transcription response

5. Available Models Documentation

## Supported Models

| Model | Description | Best For |
|-------|-------------|----------|
| `anthropic/claude-sonnet-4-20250514` | Latest Claude model | General purpose, high quality |
| `anthropic/claude-haiku-20240307` | Faster, lighter model | Quick summaries |

*Model availability may vary by region*

6. Rate Limits and Constraints

## Limits

- **Rate limit**: 100 requests per minute
- **Max transcript length**: 100,000 characters combined
- **Max output size**: 8,000 characters
- **Timeout**: 60 seconds

Structural Improvements

7. Reorganize Information Flow

Current structure is confusing. Recommend:

1. Overview (what it does, use cases)
2. Prerequisites
3. Request Format (endpoint, headers, body schema)
4. Response Format (success/error schemas)
5. Examples (diverse, practical scenarios)
6. Error Handling
7. Limits and Best Practices

8. Add Practical Guidance

## Best Practices

- **Context is powerful**: Provide specific instructions like "Focus on financial metrics" or "Extract action items"
- **Temperature tuning**: Use 0 for consistent results, 0.3-0.7 for more creative summaries
- **Chunking large content**: For very long transcripts, consider breaking into smaller segments

## Common Use Cases

- **Meeting summaries**: Extract key decisions and action items
- **Interview analysis**: Identify main themes and insights
- **Podcast highlights**: Create engaging show notes
- **Research synthesis**: Combine findings from multiple sources

User Experience Issues

9. Error Handling Guidance

Add comprehensive error documentation:

## Error Handling

| Status Code | Common Causes | Solutions |
|-------------|---------------|-----------|
| 400 | Missing required fields, invalid transcript_ids | Verify request format and transcript IDs |
| 401 | Invalid API key | Check API key in dashboard |
| 404 | Transcript not found | Ensure transcript exists and is accessible |
| 429 | Rate limit exceeded | Implement exponential backoff |

10. Interactive Elements

• Add “Try it” button with live API testing
• Include response examples for each request example
• Add copy buttons for code snippets

Priority Implementation Order

1. High Priority (Fix immediately):

   • Add request body schema
   • Add response schema with examples
   • Replace redundant examples with diverse ones

2. Medium Priority (Next iteration):

   • Add prerequisites section
   • Restructure information flow
   • Add error handling guide

3. Low Priority (Enhancement):

   • Add interactive elements
   • Expand best practices
   • Add use case examples

This documentation currently provides insufficient information for users to successfully implement the API. The suggested improvements will transform it into a comprehensive, user-friendly reference.

---