# Summarize a video
Generate a title, description, and keyword tags for a video using the Mux Robots API.
Generate a title, description, and keyword tags for a video. This is useful for auto-populating metadata in a CMS, improving search and discovery, or creating social media descriptions from video content. See the Summarize API reference for the full endpoint specification. See [Mux Robots pricing](/docs/pricing/overview#mux-robots-pricing) for unit costs.
Summarization works best when your asset has a text track. Without one, the workflow relies on sampled stills from the video, which can reduce accuracy. For the best results, make sure your asset has captions, either [auto-generated](/docs/guides/add-autogenerated-captions-and-use-transcripts) or [manually added](/docs/guides/add-subtitles-to-your-videos), before running a summarize job.
## Create a `summarize` job
```bash
curl https://api.mux.com/robots/v0/jobs/summarize \
-H "Content-Type: application/json" \
-X POST \
-d '{
"parameters": {
"asset_id": "YOUR_ASSET_ID",
"tone": "neutral"
}
}' \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
```
This request is **asynchronous**. The `POST` returns immediately with the job in `pending` status and does not include results. **We strongly recommend listening for the [`robots.job.summarize.completed` webhook](/docs/guides/robots#webhooks)** — the payload contains the full completed job, so no follow-up API call is needed. If webhooks aren't an option, you can poll `GET /robots/v0/jobs/summarize/{JOB_ID}` with the `id` from the response until the status is `completed`.
## Parameters
| Parameter | Type | Description |
| :-- | :-- | :-- |
| `asset_id` | string | **Required.** The Mux asset ID of the video to summarize. |
| `tone` | string | Tone for the generated summary. `neutral` for straightforward, factual analysis. `playful` for witty, conversational copy (good for social media). `professional` for polished, executive-level language (good for reports or investor updates). |
| `title_length` | integer | Maximum title length in words. |
| `description_length` | integer | Maximum description length in words. |
| `tag_count` | integer | Number of tags to generate. Defaults to 10. |
| `language_code` | string | BCP 47 language code of the caption track to analyze (e.g. `en`, `fr`). When omitted, the SDK uses the default track. |
| `output_language_code` | string | BCP 47 language code for the generated summary output (e.g. `en`, `fr`, `ja`). Auto-detected from the transcript if omitted. |
| `output_steering` | object | Curated controls that guide summary style, audience, brand terminology, and tags without changing the output schema. See [Output steering](#output-steering). |
### Output steering
Use `output_steering` when you want best-effort control over how the summary is generated. These fields guide the workflow but do not guarantee exact output. `output_steering` replaces the legacy `prompt_overrides` parameter.
| Field | Type | Description |
| :-- | :-- | :-- |
| `summary_style` | string | Preferred style for the generated title and description. Supported values: `concise`, `detailed`, and `editorial`. |
| `audience` | string | Intended audience used to guide the generated title and description. |
| `brand_terms` | array of strings | Preferred brand or domain terms to use when supported by the source content. |
| `tag_taxonomy` | object | Controlled vocabulary for generated tags. Tags may be deterministically filtered to this vocabulary after generation. |
| `tag_taxonomy.name` | string | Optional customer-facing name for the taxonomy. |
| `tag_taxonomy.values` | array | Controlled vocabulary values. Each value has a required `label` and optional `description` and `aliases`. |
| `tag_taxonomy.allow_other` | boolean | When `false`, generated tags are filtered to taxonomy labels and aliases. When `true`, unmatched tags may remain. |
```json
{
"parameters": {
"asset_id": "YOUR_ASSET_ID",
"tone": "professional",
"output_steering": {
"summary_style": "concise",
"audience": "online shoppers comparing kitchen gadgets",
"brand_terms": ["Ember", "Ember Ceramic Mug 2"],
"tag_taxonomy": {
"name": "Product categories",
"values": [
{
"label": "Smart home",
"description": "App-connected or temperature-controlled devices",
"aliases": ["connected device", "smart gadget"]
},
{
"label": "Kitchen accessories"
}
],
"allow_other": true
}
}
}
}
```
## Output
The `outputs` object is included in the job once its status is `completed`. You'll receive it on the [`robots.job.summarize.completed`](/docs/guides/robots#webhooks) webhook (recommended), or you can fetch it with `GET /robots/v0/jobs/summarize/{JOB_ID}`. It contains:
| Field | Type | Description |
| :-- | :-- | :-- |
| `title` | string | Generated title capturing the essence of the video. |
| `description` | string | Generated description of the video content (typically 2-4 sentences). |
| `tags` | array | Generated keyword tags for the video. |
## Example response
This is the payload delivered to the [`robots.job.summarize.completed`](/docs/guides/robots#webhooks) webhook, and the same shape you get from `GET /robots/v0/jobs/summarize/{JOB_ID}`:
```json
{
"data": {
"id": "rjob_abc123",
"workflow": "summarize",
"status": "completed",
"units_consumed": 1,
"parameters": {
"asset_id": "YOUR_ASSET_ID",
"tone": "professional",
"output_steering": {
"summary_style": "concise",
"audience": "online shoppers comparing kitchen gadgets",
"brand_terms": ["Ember", "Ember Ceramic Mug 2"],
"tag_taxonomy": {
"name": "Product categories",
"values": [
{
"label": "Smart home",
"description": "App-connected or temperature-controlled devices",
"aliases": ["connected device", "smart gadget"]
},
{
"label": "Kitchen accessories"
}
],
"allow_other": true
}
}
},
"outputs": {
"title": "Ember Ceramic Mug 2 — Temperature Control Demo",
"description": "A hands-on look at the Ember Ceramic Mug 2, demonstrating its app-controlled temperature settings, battery life, and auto-sleep feature on the charging coaster.",
"tags": ["ceramic mug", "temperature control", "smart mug", "kitchen gadget", "gift idea", "coffee accessories", "app-controlled", "rechargeable", "white", "14oz"]
}
}
}
```