Learn how to use the Mux Robots API to run AI-powered workflows on your videos, including summarization, moderation, chapter generation, and more.
The Mux Robots API uses AI to extract structured data from your videos. Instead of integrating third-party AI services, managing async job queues, handling retries and failures, and writing custom glue code to tie it all together, you can send a single API request with an asset ID and get results back directly.
The Robots API is our recommended, batteries-included approach for adding AI to your video workflows — it handles model selection, prompting, retries, and webhook delivery so you can focus on using the results.
Need more control?
If you want to build your own AI workflows from lower-level primitives (transcripts, embeddings, custom prompts, your choice of LLM provider), check out @mux/ai — our open-source TypeScript SDK. It's a great fit when you need to customize the pipeline beyond what the Robots API exposes.
| Workflow | Description |
|---|---|
| Summarize | Generate a title, description, and tags for a video |
| Moderate | Analyze a video for inappropriate content |
| Generate chapters | Create timestamped chapters from video content |
| Ask questions | Ask questions about a video and get structured answers |
| Find key moments | Identify the most compelling moments in a video |
| Translate captions | Translate existing captions to another language |
The Robots API is organized around jobs. A job represents a single unit of work — one row from the table above. Each type of work is called a workflow.
The general pattern is:
pending → processing → completed (or errored). A job can also be cancelled via the cancel endpoint. We strongly encourage using webhooks for status changes, but jobs can also be retrieved through the GET /robots/v0/jobs/{workflow}/{JOB_ID} endpoint.outputs field once the status is completed.Every status change fires a webhook event. This lets you react to completed jobs without polling. The event type follows the pattern robots.job.{workflow}.{status}:
| Event type | Description |
|---|---|
robots.job.{workflow}.pending | Job was created and is waiting to be picked up. |
robots.job.{workflow}.processing | Job is actively running. |
robots.job.{workflow}.completed | Job finished successfully. The full job object, including outputs, is in event.data. |
robots.job.{workflow}.errored | Job failed. Check event.data.errors for details. |
robots.job.{workflow}.cancelled | Job was cancelled before it completed. |
For example, a completed moderation job sends a robots.job.moderate.completed event. A completed summarization job sends robots.job.summarize.completed.
Note that multi-word workflow names use underscores in event types (e.g. robots.job.ask_questions.completed, robots.job.find_key_moments.completed), even though the API endpoints use hyphens.
The webhook payload's data field contains the full job object — the same shape you'd get from polling the job endpoint — so you can read outputs directly from the event without making an additional API call.
All Robots API endpoints live under /robots/v0/.
The Robots API uses the same Mux API token authentication as the rest of the Mux API. Include your token ID and secret using HTTP Basic Auth.
Required scope
Your access token must have the robots:* scope in order to make requests to any Robots API endpoint. You can create or update access tokens in the Mux Dashboard.
curl https://api.mux.com/robots/v0/jobs/summarize \
-H "Content-Type: application/json" \
-X POST \
-d '{ "parameters": { "asset_id": "YOUR_ASSET_ID" } }' \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}Every job includes the following common fields:
| Field | Description |
|---|---|
id | Unique job identifier |
status | Current status: pending, processing, completed, errored, or cancelled |
workflow | The workflow type (e.g. summarize, moderate) |
created_at | Unix timestamp when the job was created |
updated_at | Unix timestamp when the job was last updated |
passthrough | An arbitrary string you can include when creating the job, returned as-is in responses |
parameters | The input parameters for this job. Varies by workflow — see each workflow's guide for details. |
outputs | Workflow results, present when status is completed |
units_consumed | Number of Mux AI units consumed by this job |
errors | Error details, present when status is errored. See the Robots API referenceAPI for the full error structure. |
resources | Related Mux resources linked to this job |
You can retrieve, list, cancel, and delete jobs across all workflows.
Retrieve a job by workflow and job ID:
curl https://api.mux.com/robots/v0/jobs/{workflow}/{JOB_ID} \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}Replace {workflow} with the workflow name used when the job was created (e.g. summarize, moderate, generate-chapters). The response includes the full job object with outputs when the job is completed.
List jobs with optional filters:
curl "https://api.mux.com/robots/v0/jobs?workflow=summarize&status=completed&limit=10" \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}You can filter by workflow, status, asset_id, and paginate with limit (default 25, max 100) and page (default 1).
Cancel a job that is pending or processing. The job's status will transition to cancelled:
curl -X POST https://api.mux.com/robots/v0/jobs/{JOB_ID}/cancel \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}