yalla
GitHub

For developers and AI agents

One JSON API to probe, download and convert media.

The same engine behind this site, as a REST API with an OpenAPI 3.1 document and a Model Context Protocol server. Point an agent at it and it can fetch a video in the exact quality you asked for, extract audio, or convert a file, then hand you a link.

OpenAPI JSONFull referencehttps://yalla-api.mouse-on.com/api/v1

What an agent can do here

  • Probe any URL

    Title, duration, thumbnail and every stream a site serves — resolution, fps, codec, size — from 1000+ sites. Nothing is downloaded.

    POST /api/v1/probe

  • Download video or audio

    Ask for "1080" and get the best H.264 stream at that height merged with audio, or an exact formatId. Audio-only as MP3, M4A, Opus, FLAC, WAV or OGG. Playlists arrive as one ZIP.

    POST /api/v1/download

  • Convert files

    Upload a file, then re-encode, compress to a target size, trim, extract audio or make a GIF. Same presets the web UI uses.

    PUT /api/v1/uploads → POST /api/v1/convert

  • Wait, then fetch

    Every job is JSON with progress and stage. Long-poll with wait (up to 55 s) instead of spinning, then stream the result from an absolute file URL until it expires.

    GET /api/v1/jobs/{id}?wait=55

Quick start

Three calls. Bodies are JSON, responses are JSON, errors are always { error: { code, message } }.

Probe
# 1. See what is available — nothing is downloaded yetcurl -s -X POST https://yalla-api.mouse-on.com/api/v1/probe \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.youtube.com/watch?v=aqz-KE-bpKQ"}'
Download and wait
# 2. Start a 1080p download and hold the request up to 45 s (max 55)curl -s -X POST https://yalla-api.mouse-on.com/api/v1/download \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.youtube.com/watch?v=aqz-KE-bpKQ","quality":"1080","wait":45}'# 200 + the finished job if it completed in time, else 202 — keep polling with ?wait=55curl -s "https://yalla-api.mouse-on.com/api/v1/jobs/<id>?wait=55"
Fetch the file
# 3. files[0].url from the job — -OJ keeps the server's filenamecurl -OJ https://yalla-api.mouse-on.com/api/v1/jobs/<id>/files/0

Result files are deleted after the instance's FILE_TTL_MINUTES (see files[].expiresAt). Job state lives in memory — a server restart forgets unfinished jobs.

Auth and metering

  1. API keys are optional. When the operator sets API_KEYS, send Authorization: Bearer <key> (or X-API-Key) with every call; otherwise the API is open.
  2. Metered instances answer billable calls with HTTP 402 and x402 payment details from Cloudflare's Monetization Gateway. An agent wallet pays and retries automatically; Yalla itself never handles money.
  3. Discovery is always free: GET /api/v1, openapi.json, this page and /llms.txt. Polling a job and fetching its file are never billed either.

MCP server

Streamable HTTP, stateless, at https://yalla-api.mouse-on.com/mcp. Add it to Claude Desktop, Claude Code, Cursor or any MCP client and the model gets five tools plus the OpenAPI document as a resource.

Client configjson
{
  "mcpServers": {
    "yalla": {
      "url": "https://yalla-api.mouse-on.com/mcp"
    }
  }
}
Inspector
# Poke at the server from a terminalnpx -y @modelcontextprotocol/inspector --cli https://yalla-api.mouse-on.com/mcp --method tools/list
  • probe_media

    Inspect a URL: title, duration, qualities, audio streams.

  • download_media

    Start a download, wait for it, return the file URL.

  • get_job

    Poll or long-poll a job until it finishes.

  • cancel_job

    Stop a queued or running job.

  • list_capabilities

    Formats, limits, auth and pricing for this instance.

  • yalla://openapi

    Resource: the full OpenAPI 3.1 document.

Endpoints

Every response carries X-Yalla-Version: 1. “Billed” marks the calls a metered instance charges for — one request, one charge.

MethodPathWhat it doesBilled
GET/api/v1Capabilities and limitsFree
GET/api/v1/openapi.jsonThis OpenAPI documentFree
POST/api/v1/probeInspect a media URLYes
POST/api/v1/downloadStart a download jobYes
PUT/api/v1/uploadsUpload a file for conversionYes
POST/api/v1/convertConvert an uploaded fileYes
GET/api/v1/jobs/{id}Get a job (optionally long-poll)Free
DELETE/api/v1/jobs/{id}Cancel a jobFree
GET/api/v1/jobs/{id}/files/{index}Download a result fileFree

Pricing

Free while self-hosted. Public instances may meter requests via Cloudflare's Monetization Gateway.

Operators: docs/MONETIZATION.md walks through enabling per-request charging with Cloudflare.

This instance: https://yalla-api.mouse-on.com. Only download content you own or have permission to use.