Free audio extraction API — cut YouTube audio to MP3 with one request

Overview

• Endpoint: POST https://api.samplecut.app/v1/downloads
• Authentication: none. Calls are rate-limited per IP address (see Limits).
• Request: a JSON body, sent with Content-Type: application/json.
• Response: JSON, or the audio file when "response": "file" is set. Errors are always JSON.
• Specification: OpenAPI 3.1. Import it into Postman or Insomnia, or use it to generate a typed client.

Quickstart

Only url is required. With no range you get the full track, and with no format you get MP3.

curl -X POST https://api.samplecut.app/v1/downloads \
  -H 'content-type: application/json' \
  -d '{"url": "https://www.youtube.com/watch?v=jNQXAC9IVRw"}'

A successful call returns 201 Created:

{
  "id": "969cb27b-…",
  "download_url": "https://api.samplecut.app/d/969cb27b-…",
  "expires_at": "2026-10-27T17:08:46.886Z",
  "title": "Me at the zoo",
  "filename": "samplecut-me-at-the-zoo.mp3",
  "format": "mp3",
  "full": true,
  "track_duration_sec": 19.05,
  "editor_url": "https://samplecut.app/?url=…"
}

The request is synchronous: the response arrives once the file is ready. That usually takes a few seconds, and up to about a minute for an hour-long source, so set a client timeout of at least 120 seconds.

Request body

Example: a 6-second WAV clip.

curl -X POST https://api.samplecut.app/v1/downloads \
  -H 'content-type: application/json' \
  -d '{"url": "https://youtu.be/jNQXAC9IVRw", "start_sec": 2, "end_sec": 8, "format": "wav"}'

A ranged response also includes start_sec and end_sec, and full is false. A body sent with any other content type is rejected with 415.

Returning the file directly

With "response": "file", the API returns 200 OK with the audio as the response body (audio/mpeg or audio/wav). The filename is set in Content-Disposition, so curl can save the file in one step:

curl -X POST https://api.samplecut.app/v1/downloads -OJ \
  -H 'content-type: application/json' \
  -d '{"url": "https://youtu.be/jNQXAC9IVRw", "response": "file"}'

Metadata comes in response headers: X-Samplecut-Title (URL-encoded), X-Samplecut-Download-Url and X-Samplecut-Expires-At. If a transfer is interrupted, use the download URL to fetch the file again without spending another call.

Client examples

Node.js 18+ (built-in fetch):

const res = await fetch('https://api.samplecut.app/v1/downloads', {
  method: 'POST',
  headers: { 'content-type': 'application/json', 'x-client-name': 'my-app' },
  body: JSON.stringify({ url: 'https://youtu.be/jNQXAC9IVRw' }),
  signal: AbortSignal.timeout(120_000),
})
const body = await res.json()
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`)
console.log(body.download_url)

Python (requests):

import requests

res = requests.post(
    "https://api.samplecut.app/v1/downloads",
    json={"url": "https://youtu.be/jNQXAC9IVRw", "start_sec": 2, "end_sec": 8},
    headers={"X-Client-Name": "my-app"},
    timeout=120,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["download_url"])

Call the API from a server, a script or a CLI. CORS is limited to samplecut.app, so a browser page on another origin cannot call it directly. Send an optional X-Client-Name header with your app's name; it lets us see which integrations are in use and keep them working.

Errors

Every error response has the same shape. code is stable and safe to branch on. message is readable by an end user. retryable is true only when the same request can succeed later.

{ "error": { "code": "unsupported_url", "message": "…", "retryable": false } }

The OpenAPI document is the authoritative contract for every field and error code.

Integrate with an AI coding assistant

To have Claude Code, Cursor, Copilot or ChatGPT write the integration, paste this prompt into it. It points the assistant at this page and the OpenAPI document, so the code it writes follows the real contract instead of a guessed one.

Integrate the Samplecut audio API into this project.

Docs: https://samplecut.app/developers
OpenAPI 3.1 spec: https://api.samplecut.app/v1/openapi.json

Read both before writing code. Requirements:
- Call POST https://api.samplecut.app/v1/downloads from server-side code only (CORS blocks other browser origins). No API key is needed.
- Send JSON with Content-Type: application/json and an X-Client-Name header set to this app's name.
- Use a request timeout of at least 120 seconds; the call is synchronous.
- Support the optional fields start_sec, end_sec or duration_sec, format ("mp3" | "wav") and response ("url" | "file").
- download_url expires after about an hour: download and store the file, never the URL.
- Handle errors by error.code. On 429, wait Retry-After seconds and retry; retry 502 with backoff; surface error.message to the user otherwise.
- Write a typed client based on the OpenAPI schema, plus a test for the error handling.

Want the assistant to cut audio for you itself, without writing any code? Add the MCP connector instead. For a one-page overview with copyable samples, see samplecut.app/developers.

Limits

• Rate limit: 10 calls per 10 minutes per IP address, shared with the site's own per-IP allowance. Repeat cuts of the same source within a few minutes reuse the downloaded audio, so cutting one video into many clips is cheap.
• Source length: up to 60 minutes.
• Link lifetime: download_url expires after about an hour (see expires_at). Store the file, not the URL.
• Availability: best effort, with no SLA. The API is free and shares infrastructure with samplecut.app.

Need higher limits? Tell us what you're building through the feedback link on samplecut.app.