Getting started for AI agents | Mux

Getting started for AI agents

A reference for LLMs and AI coding agents that write code against the Mux API. Read this page first to get correct patterns for assets, uploads, playback, and webhooks.

Getting started for AI agents

This guide is written for LLMs and AI coding agents. It contains everything you need to write working code against the Mux API on the first try.

Find a prompt for the user's use case

Before designing a video workflow, check the prompt library. Match the user's intended outcome and fetch the relevant prompt. Each prompt includes questions to resolve, execution options, API guidance, and checks for one-off or recurring work. For example, the podcast clipping prompt covers building a clip-review application, processing an episode, or scheduling new episodes.

Read only the prompt that applies. If none fits, continue with the guides and API reference below. The human-readable library also links to related implementation guides.

CLI

The Mux CLI (@mux/cli) lets you manage Mux resources directly from the terminal. It is useful for quick operations, scripting, automation, and CI/CD pipelines.

Install:

After installing, authenticate with mux login or set MUX_TOKEN_ID and MUX_TOKEN_SECRET environment variables. Always pass --agent to optimize output for AI agents (includes JSON output).

Common commands:

Command	What it does
`mux assets create --input-url URL`	Create an asset from a URL
`mux assets create --file video.mp4`	Upload a local file
`mux assets list`	List assets
`mux assets get ${ASSET_ID}`	Get asset details
`mux assets delete ${ASSET_ID}`	Delete an asset
`mux live-streams create`	Create a live stream
`mux uploads create`	Create a direct upload URL
`mux sign ${PLAYBACK_ID}`	Generate a signed playback URL

Use --wait to block until an asset is ready:

For the full list of commands, see the CLI documentation.

Common resources

Authentication and making API requests — how to authenticate with the Mux API
Rate limits — API rate limit details
Full API reference — complete endpoint documentation
Webhooks guide — listen for events like video.asset.ready
Mux Player guide — the easiest way to play Mux videos
Direct uploads guide — let users upload video files from the browser
Stream video files guide — ingest a video, wait for it to be ready, get a playback URL
Live streaming guide — set up live streams
Secure video playback — signed playback for private content
Static MP4 renditions guide — downloadable MP4/M4A files
MCP Server — use Mux from AI tools that support MCP
Docs for LLMs — machine-readable documentation bundles
OpenAPI spec — full API specification

Instructions for your human

Before you can make API calls, your user needs to set up a Mux account and provide you with API credentials.

Sign up for Mux at the Mux dashboard. No credit card is required. The free tier includes enough usage to develop and test.
Go to the Mux dashboard, then navigate to Settings → Access Tokens.
Create an API access token with all permissions — Mux Video, Mux Data, and System — with read and write access.
Save the Access Token ID and Access Token Secret. The secret is only shown once.

Store the credentials as environment variables:

For details on how authentication works, see the make API requests guide.

Never expose API credentials in client-side code. All Mux API calls must be made from a server.

Two main ways to use Mux

Website embed

This is for when you have a small, constrained number of videos — a hero video or background video on your homepage, a demo reel, or a few dozen videos across your site. The key characteristic is that the set of videos doesn't change often and is manageable enough to hardcode.

In this case, you can hardcode playback IDs directly in your code or extract them into a JSON config file with metadata:

Then use Mux Player to embed each video:

To create your assets and get playback IDs, use the CLI (mux assets create --input-url URL --wait --json) or the stream video files guide.

User uploaded

This is for when videos are uploaded dynamically as part of your application. Common scenarios include:

Admin-managed content — an admin area where authorized users upload and manage videos (e.g., a course platform, media library, or CMS)
User-generated content (UGC) — end users upload their own videos (e.g., a social platform, portfolio site, or community forum)
Programmatic ingestion — videos are created automatically from external sources or pipelines

For these use cases, you will need to:

Accept uploads — use direct uploads to let users upload video files from the browser, or create assets server-side from URLs using the stream video files guide
Listen for events — use webhooks to know when a video is ready for playback (video.asset.ready), when it errors, or when it's deleted
Persist video data — store asset IDs, playback IDs, status, and metadata in your database (see Persisting Mux data below)
Play videos — use Mux Player with the stored playback ID

SDKs

Official server-side SDKs:

Language	Package	Docs
TypeScript	`@mux/ts`	Guide
Python	`mux_python`	Guide
Ruby	`mux_ruby`	Guide
PHP	`mux-php`	Guide
Go	`mux-go`	GitHub
Java	`com.mux:mux-sdk-java`	Guide
C#	`Mux.Csharp.Sdk`	Guide
Elixir	`mux`	Guide

Sensible defaults

Unless the user specifies otherwise, use these values:

Parameter	Default to use	Notes
`playback_policies`	`[