Samplecut API — audio from any video link, in 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.

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.