Feedback: api-reference-transcripts-submit

Documentation Feedback

Original URL: https://www.assemblyai.com/docs/api-reference/transcripts/submit
Category: api-reference
Generated: 05/08/2025, 4:30:26 pm

---

Claude Sonnet 4 Feedback

Generated: 05/08/2025, 4:30:25 pm

Technical Documentation Analysis & Improvement Recommendations

Critical Issues Requiring Immediate Action

1. Missing Request Body Documentation

Problem: No structured documentation of request parameters despite showing 30+ options in the example.

Solution: Add a comprehensive “Request Body” section:

## Request Body

### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `audio_url` | string | URL of the media file to transcribe. Must be publicly accessible. |

### Optional Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `language_code` | string | `en_us` | Language of the audio file ([supported languages](link)) |
| `auto_chapters` | boolean | `false` | Enable automatic chapter detection |
| `speaker_labels` | boolean | `false` | Enable speaker diarization |
| `sentiment_analysis` | boolean | `false` | Enable sentiment analysis on transcript |
| `audio_start_from` | integer | `0` | Start transcription from this time (milliseconds) |
| `audio_end_at` | integer | `null` | End transcription at this time (milliseconds) |
| ... | ... | ... | ... |

2. Missing Response Documentation

Problem: Only HTTP status codes listed, no actual response structure.

Solution: Add complete response examples:

## Response Body

### Success Response (200)
```json
{
  "id": "5551722-f677-48a6-9287-39bb9a5c0922",
  "language_model": "assemblyai_default",
  "acoustic_model": "assemblyai_default",
  "language_code": "en_us",
  "status": "queued",
  "audio_url": "https://assembly.ai/wildfires.mp3",
  "text": null,
  "words": null,
  "confidence": null,
  "created": "2023-01-01T12:00:00.000000"
}

Error Response (400)

{
  "error": "Invalid audio_url: URL must be publicly accessible"
}

### 3. **Redundant Examples**
**Problem**: 7 identical minimal examples after one comprehensive example.

**Solution**: Replace with targeted examples:
```markdown
## Examples

### Basic Transcription
```shell
curl -X POST https://api.assemblyai.com/v2/transcript \
     -H "Authorization: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "audio_url": "https://example.com/audio.mp3"
     }'

Advanced Features

# Example with speaker labels and sentiment analysis
curl -X POST https://api.assemblyai.com/v2/transcript \
     -H "Authorization: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "audio_url": "https://example.com/meeting.mp3",
       "speaker_labels": true,
       "sentiment_analysis": true,
       "auto_chapters": true
     }'

PII Redaction

# Example with PII redaction
curl -X POST https://api.assemblyai.com/v2/transcript \
     -H "Authorization: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "audio_url": "https://example.com/confidential.mp3",
       "redact_pii": true,
       "redact_pii_policies": ["us_social_security_number", "credit_card_number"]
     }'

## Structure & Organization Issues

### 4. **Improve Content Flow**
**Current order**: Endpoint → Note → Description → Response → Examples

**Recommended order**:
```markdown
# Transcribe Audio

Brief description of what this endpoint does.

## Endpoint
POST https://api.assemblyai.com/v2/transcript

## Authentication
Include authentication section with clear API key instructions.

## Request Body
[Detailed parameter documentation]

## Response
[Success and error response examples]

## Examples
[Practical, varied examples]

## Error Handling
[Common errors and solutions]

## Rate Limits & Best Practices

Missing Critical Information

5. Authentication Details

Add:

## Authentication
This endpoint requires API key authentication. Include your API key in the Authorization header:

Authorization: YOUR_API_KEY

Get your API key from the [AssemblyAI Dashboard](link).

6. File Requirements & Limitations

Add:

## Audio File Requirements
- **Supported formats**: MP3, WAV, FLAC, M4A, OGG, WEBM
- **Maximum file size**: 2.2 GB
- **Maximum duration**: 12 hours
- **Audio URL**: Must be publicly accessible (no authentication required)
- **Supported sample rates**: 8kHz to 48kHz

7. Processing Workflow

Add:

## How It Works
1. Submit audio URL via POST request
2. Receive transcript ID in response (status: "queued")
3. Audio begins processing immediately
4. Poll the transcript status using the ID or use webhooks
5. Retrieve completed transcript when status is "completed"

**Next steps**: Use [GET /transcript/{id}](link) to check status and retrieve results.

User Experience Improvements

8. Add Validation Rules

## Validation Rules
- `audio_url`: Must be a valid, publicly accessible URL
- `language_confidence_threshold`: Float between 0.0 and 1.0
- `speakers_expected`: Integer between 1 and 10
- `speech_threshold`: Float between 0.0 and 1.0

9. Common Error Solutions

## Troubleshooting
| Error | Cause | Solution |
|-------|-------|----------|
| 400: Invalid audio_url | URL not accessible | Ensure URL is public and returns audio file |
| 401: Unauthorized | Invalid API key | Check API key in Authorization header |
| 429: Too many requests | Rate limit exceeded | Implement exponential backoff |

10. Add Related Endpoints

## Related Endpoints
- [Check transcript status](link-to-get-transcript)
- [Upload local files](link-to-upload)
- [Real-time transcription](link-to-streaming)

Quick Fixes

1. Fix API key placeholder: Change <apiKey> to YOUR_API_KEY for consistency
2. Add link targets: Make all referenced links functional
3. Improve EU server note: Move to a dedicated “Regional Options” section
4. Add response time expectations: “Processing typically takes 15-30% of audio duration”

This documentation needs significant expansion to be production-ready. The current version would likely frustrate developers due to missing parameter explanations, response formats, and practical guidance.

---