Agent guide

Agents should use AudioLasso through the highest-level interface available.

Use this order:

1. MCP server, when the agent runtime supports MCP tools.
2. TypeScript SDK, when the agent can write or run Node.js code.
3. CLI, when the agent is operating from a shell.
4. OpenAPI, when the agent is generating an integration in another language.

Core workflow

Every interface follows the same flow:

1. Create or load an API key.
2. Submit an audio separation job with a prompt.
3. Poll or wait until the request reaches COMPLETED.
4. Fetch the result and use data.target.url for the isolated sound.

For local files, upload first and submit the returned file_id.

Treat polling as the durable base path. Streaming is useful for live CLI or UI sessions, and webhooks are useful for backend callbacks.

MCP

Use MCP when the agent should call AudioLasso directly as tools.

{
  "mcpServers": {
    "audiolasso": {
      "command": "npx",
      "args": ["-y", "audiolasso", "mcp"],
      "env": {
        "AUDIOLASSO_API_KEY": "al_live_..."
      }
    }
  }
}

The server exposes tools for upload, submit, status, wait, result, and models.

Read MCP server for the full setup.

SDK

Use the SDK when generating Node.js code:

import { createAudioLasso } from "audiolasso";

const client = createAudioLasso();

const job = await client.separate({
  audioUrl: "https://example.com/audio.wav",
  prompt: "isolate the lead vocal",
});

const result = await client.waitForResult(job.request_id);

console.log(result.data.target.url);

Read TypeScript SDK for method names and upload examples.

CLI

Use the CLI when the agent is already working in a terminal:

export AUDIOLASSO_API_KEY="al_live_..."

npx audiolasso separate ./song.wav \
  --prompt "isolate the vocals" \
  --output-dir ./stems

Read CLI for status, result, and login commands.

Other languages

Use the OpenAPI spec when building a client in Python, Go, Swift, Ruby, or another language:

https://audiolasso.dev/v1/openapi.json

The important endpoints are:

• POST /v1/files
• GET /v1/files/{file_id}
• POST /v1/queue/audio/separate
• GET /v1/queue/requests/{request_id}/status
• GET /v1/queue/requests/{request_id}/result
• GET /v1/queue/requests/{request_id}/status/stream

Skill publishing

A skill is useful when you want an agent to remember the AudioLasso workflow, not when you need live API access by itself.

Keep a skill small:

---
name: audiolasso
description: Use AudioLasso to isolate sounds from audio or video. Use when a task needs vocal isolation, instrument separation, speech cleanup, background-noise removal, or agent-driven audio separation.
---

Use the MCP server if available. Otherwise use the TypeScript SDK or CLI.

Core workflow:
1. Load AUDIOLASSO_API_KEY.
2. For local files, upload first.
3. Submit a separation job with a plain-language prompt.
4. Wait for COMPLETED.
5. Return target and residual output URLs.

Docs:
- https://audiolasso.dev/llms.txt
- https://audiolasso.dev/docs/mcp
- https://audiolasso.dev/v1/openapi.json

Do not put secrets in a skill. Put API keys in the agent runtime environment.