{"openapi":"3.1.0","info":{"title":"Samplecut API","version":"1.0.0","summary":"Cut the audio of a YouTube, TikTok, Instagram, SoundCloud or X link to MP3 or WAV.","description":"Free and anonymous: no API key, no signup. Responses only gain fields, never lose them. Guide: https://samplecut.app/guides/free-audio-api"},"servers":[{"url":"https://api.samplecut.app"}],"externalDocs":{"url":"https://samplecut.app/guides/free-audio-api"},"paths":{"/v1/downloads":{"post":{"operationId":"createDownload","summary":"Cut a link’s audio; get a download link or the file","description":"Waits until the file is ready (seconds, up to about a minute for long videos): use a client timeout of at least 120 s. Limits: 10 calls per 10 minutes per IP, sources up to 60 minutes long, plus the site's shared extract and download limits. Meant for servers and scripts: browsers on other origins are refused by CORS.","parameters":[{"in":"header","name":"X-Client-Name","required":false,"description":"Optional name of your app, so integrations can be told apart.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadRequest"}}}},"responses":{"200":{"description":"The audio itself (response: \"file\").","headers":{"Content-Disposition":{"description":"attachment; filename=\"…\"; filename*=UTF-8''…","schema":{"type":"string"}},"X-Samplecut-Title":{"description":"The track title, URL-encoded.","schema":{"type":"string"}},"X-Samplecut-Download-Url":{"description":"A link to fetch the same file again until it expires.","schema":{"type":"string","format":"uri"}},"X-Samplecut-Expires-At":{"description":"When that link expires (ISO 8601).","schema":{"type":"string","format":"date-time"}}},"content":{"audio/wav":{"schema":{"type":"string","contentMediaType":"audio/wav"}},"audio/mpeg":{"schema":{"type":"string","contentMediaType":"audio/mpeg"}}}},"201":{"description":"The cut is ready: a short-lived download link (the default, response: \"url\").","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Download"}}}},"400":{"description":"The request or the link can’t be cut.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["invalid_request","unsupported_url","invalid_range","soundcloud_not_track","soundcloud_short_link","set_not_track"]},"message":{"type":"string","description":"A sentence you can show to a person."},"retryable":{"type":"boolean","description":"True only when trying again can help."},"downloadUrl":{"type":"string","format":"uri","description":"For a refused track that has its own download page on the source, that page."}}}}}}}},"415":{"description":"The body was not sent as application/json.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["unsupported_media_type"]},"message":{"type":"string","description":"A sentence you can show to a person."},"retryable":{"type":"boolean","description":"True only when trying again can help."},"downloadUrl":{"type":"string","format":"uri","description":"For a refused track that has its own download page on the source, that page."}}}}}}}},"422":{"description":"The source was refused: too long, private, removed, region-blocked, DRM-protected or a preview.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["too_long","extract_failed","clip_expired","drm","preview_only"]},"message":{"type":"string","description":"A sentence you can show to a person."},"retryable":{"type":"boolean","description":"True only when trying again can help."},"downloadUrl":{"type":"string","format":"uri","description":"For a refused track that has its own download page on the source, that page."}}}}}}}},"429":{"description":"A rate limit was hit. Retryable after Retry-After seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string","description":"A sentence you can show to a person."},"retryable":{"type":"boolean","description":"True only when trying again can help."},"downloadUrl":{"type":"string","format":"uri","description":"For a refused track that has its own download page on the source, that page."}}}}}}}},"500":{"description":"Unexpected server error. Retryable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["internal"]},"message":{"type":"string","description":"A sentence you can show to a person."},"retryable":{"type":"boolean","description":"True only when trying again can help."},"downloadUrl":{"type":"string","format":"uri","description":"For a refused track that has its own download page on the source, that page."}}}}}}}},"502":{"description":"The platform itself didn’t answer. Retryable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["source_unreachable"]},"message":{"type":"string","description":"A sentence you can show to a person."},"retryable":{"type":"boolean","description":"True only when trying again can help."},"downloadUrl":{"type":"string","format":"uri","description":"For a refused track that has its own download page on the source, that page."}}}}}}}},"503":{"description":"The API is switched off for now.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","enum":["api_disabled"]},"message":{"type":"string","description":"A sentence you can show to a person."},"retryable":{"type":"boolean","description":"True only when trying again can help."},"downloadUrl":{"type":"string","format":"uri","description":"For a refused track that has its own download page on the source, that page."}}}}}}}}}}}},"components":{"schemas":{"DownloadRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"description":"A YouTube, TikTok, Instagram, SoundCloud or X link (short, share and mobile links work too)."},"start_sec":{"type":"number","minimum":0,"description":"Section start in seconds. Send with end_sec or duration_sec."},"end_sec":{"type":"number","exclusiveMinimum":0,"description":"Section end in seconds. Send with start_sec."},"duration_sec":{"type":"number","exclusiveMinimum":0,"description":"Section length, from start_sec (or the start of the track)."},"format":{"type":"string","enum":["wav","mp3"],"default":"mp3","description":"mp3 is 320 kbps; wav is lossless."},"response":{"type":"string","enum":["url","file"],"default":"url","description":"A download link (201) or the file itself (200)."}}},"Download":{"type":"object","required":["id","download_url","expires_at","title","filename","format","full","track_duration_sec","editor_url"],"properties":{"id":{"type":"string","format":"uuid"},"download_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"title":{"type":"string"},"filename":{"type":"string"},"format":{"type":"string","enum":["wav","mp3"]},"full":{"type":"boolean","description":"True when this is the whole track."},"start_sec":{"type":"number","description":"Only on a cut section."},"end_sec":{"type":"number","description":"Only on a cut section."},"track_duration_sec":{"type":"number"},"editor_url":{"type":"string","format":"uri","description":"Opens the same clip in the Samplecut editor."}}}}}}