Generate a title, description, and keyword tags for a video with the Mux Robots API, and steer the style, audience, and tag vocabulary. Use this workflow to fill metadata for user uploads or a large video library.
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 referenceAPI for the full endpoint specification. See Mux Robots pricing for unit costs.
Check the shared workflow prerequisites before creating a job.
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 or manually added, before running a summarize job.
summarize jobcurl https://api.mux.com/robots/v1/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.v1.job.summarize.completed webhook — 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/v1/jobs/summarize/{JOB_ID} with the id from the response until the status is completed.
| 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). An explicit value must match a ready track exactly, including case: en does not match en-US. When omitted, the first ready subtitle track in asset track order is used. See language support for Mux Robots. |
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. See language support for Mux Robots. |
output_steering | object | Curated controls that guide summary style, audience, brand terminology, and tags without changing the output schema. See Output steering. |
update_asset_meta | boolean | When true, the generated title is written to the asset's meta.title once the job completes. Best effort: a failed write does not fail the job. The outcome is reported in outputs.asset_updates. |
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. All output_steering fields are optional; include only the fields you need.
| Field | Type | Description |
|---|---|---|
scope | object | Time window in seconds on the asset timeline, with start_time and end_time. Unlike the other fields, scope is enforced: the summary is generated only from media within this window. Omit start_time to begin at the asset start, and end_time to continue through the asset end. |
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. |
{
"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
}
}
}
}The outputs object is included in the job once its status is completed. You'll receive it on the robots.v1.job.summarize.completed webhook (recommended), or you can fetch it with GET /robots/v1/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. |
asset_updates | object | Outcome of the asset title update when update_asset_meta is true, as asset_updates.title.status (updated or failed). Omitted when no update outcome was recorded. |
This example uses a five-minute asset, consuming 650 units. It is the job delivered in the robots.v1.job.summarize.completed webhook's data field and returned by GET /robots/v1/jobs/summarize/{JOB_ID}:
{
"data": {
"id": "rjob_abc123",
"workflow": "summarize",
"status": "completed",
"units_consumed": 650,
"created_at": 1746403200,
"updated_at": 1746403260,
"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"]
}
}
}