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 referenceAPI for the full endpoint specification. See 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 or manually added, before running a summarize job.
summarize jobcurl 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 — 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.
| 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. |
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. |
{
"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.job.summarize.completed 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. |
This is the payload delivered to the robots.job.summarize.completed webhook, and the same shape you get from GET /robots/v0/jobs/summarize/{JOB_ID}:
{
"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"]
}
}
}