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

# Commentaries

> AI-generated content from personas

## What is a Commentary?

A **commentary** is AI-generated content from a persona about a specific topic. Each commentary is unique to the persona who generated it, reflecting their voice, expertise, and perspective.

## Commentary Formats

Commentaries can be generated in multiple formats:

| Format  | Description                | Use Case                       |
| ------- | -------------------------- | ------------------------------ |
| `text`  | Written commentary         | Articles, social posts, embeds |
| `audio` | Voice-generated audio file | Podcasts, audio players        |
| `video` | Avatar video with audio    | Video embeds, social media     |

Specify desired formats when creating a topic:

```json theme={null}
{
  "content": "Should the Lakers trade AD?",
  "persona_ids": ["..."],
  "output_types": ["text", "audio"]
}
```

## Commentary Structure

```json theme={null}
{
  "commentary_id": "comm-abc123-...",
  "persona": {
    "id": "persona-xyz-...",
    "name": "Coach Mike",
    "image_url": "https://..."
  },
  "content": "Look, AD is still one of the best two-way players in the league...",
  "audio_url": "https://storage.unleeshed.ai/audio/comm-abc123.mp3",
  "video_url": null
}
```

| Field           | Type           | Description                      |
| --------------- | -------------- | -------------------------------- |
| `commentary_id` | string         | Unique identifier                |
| `persona`       | object         | Persona who generated this       |
| `content`       | string         | Text content (always present)    |
| `audio_url`     | string \| null | URL to audio file (if requested) |
| `video_url`     | string \| null | URL to video file (if requested) |

## Generation Time

Commentary generation is asynchronous. Typical times:

| Output Type          | Generation Time |
| -------------------- | --------------- |
| Text only            | 30-60 seconds   |
| Text + Audio         | 60-90 seconds   |
| Text + Audio + Video | 90-180 seconds  |

<Tip>
  Start with `text` output for the fastest results, then add audio/video as needed.
</Tip>

## Quality & Uniqueness

Each commentary is:

* **Unique** - Generated fresh for each request (not cached)
* **Persona-authentic** - Reflects the persona's voice and style
* **Topic-relevant** - Directly addresses the topic content
* **Safe** - Filtered for inappropriate content

## Using Commentaries

### Fetch by Topic

The most common pattern - get all commentaries for a topic:

```javascript theme={null}
const response = await fetch(
  `https://prod.api.unleeshed.ai/partner/v1/topics/${topicId}/commentaries`,
  { headers: { 'X-Api-Key': apiKey } }
);

const { data } = await response.json();
// data.commentaries = array of all completed commentaries
```

### Display Multiple Perspectives

Show commentary from multiple personas on the same topic:

```jsx theme={null}
function TopicCommentaries({ commentaries }) {
  return (
    <div className="commentaries">
      {commentaries.map(c => (
        <article key={c.commentary_id}>
          <header>
            <img src={c.persona.image_url} alt={c.persona.name} />
            <h3>{c.persona.name}</h3>
          </header>
          <p>{c.content}</p>
          {c.audio_url && <AudioPlayer src={c.audio_url} />}
        </article>
      ))}
      <footer>Powered by Unleeshed</footer>
    </div>
  );
}
```

## Related

<CardGroup cols={2}>
  <Card title="Generate Commentary" icon="waveform" href="/guides/generate-commentary">
    Step-by-step guide to generating commentary.
  </Card>

  <Card title="Display Guide" icon="desktop" href="/guides/display-commentaries">
    Best practices for displaying commentaries.
  </Card>
</CardGroup>