Files

Returns the files stored under your account, 100 per page by default, in storage order. Follow pagination.cursor while pagination.has_more is true. The list shows what is in storage: a file you deleted stays listed until it is removed for good (7 days after deletion, or when you delete it forever). Counts against the hourly account request budget. Available to free and paid accounts.

Moves one of your files to the trash. It is not erased at once: it stays recoverable for 7 days (purge_after), after which it is removed for good. Only your own files can be deleted; any other id, and a file already in the trash, returns 404. Counts against the hourly account request budget. Available to free and paid accounts.

Creates a link for downloading one of your files. Fetch download_url with a plain GET and no API key; the response is the file with a Content-Disposition: attachment header. The link works once, and only until expires_in seconds have passed (60 to 86400; 3600 if you send no body). A second request, or one after expiry, gets 403 invalid_download_token; create a new link instead. Only your own files can be linked: any other id returns 404.

Send filename to choose the name the download is saved under (ignored when longer than 200 characters). The body is optional; one that is not valid JSON is treated as empty. Counts against the hourly account request budget. Available to free and paid accounts.

Returns how much storage your account uses. Every account includes 1 TiB; cap_bytes reports that included amount. Files in the trash still count until they are removed for good. Counts against the hourly account request budget. Available to free and paid accounts.

Starts an upload that goes straight to storage. Declare the file with content_length (and content_type), then send the file bytes with a PUT to the returned upload_url within 15 minutes. The file then appears in your library and the file list. A file can be up to 10 GiB for audio and 1 GiB for MP4 or MOV video.

upload_url is opaque: send the request to it exactly as returned, with the same Content-Type you declared, and do not parse it or add your API key (the URL itself is the credential). When direct is false the URL points back at this API instead of storage; the same PUT rules apply. Use media_url to refer to the stored file afterwards, and audio_id to attach it as a version.

Declaring the size reserves that much of your storage right away, so a file that would not fit is refused here with 413 storage_quota_exceeded, before any bytes are sent. An upload you never complete keeps its reservation until it is cleaned up. For files you want to resume, or for many parts in parallel, use an upload session instead. Counts against the hourly account request budget. Available to free and paid accounts.

Fallback target of a presigned upload. When the upload URL from the presigned upload route has direct: false, it points here: it already carries the one-time t token, so call it exactly as returned, with the file bytes as the request body and the Content-Type you declared. There is no API key on this route; the token is the credential, it works once, and a URL that is expired, used or wrong gets 403 invalid_upload_intent.

The body is read in one piece, so the limit is 100 MiB for audio. The bytes are checked: a file that is not valid audio is refused with 400 invalid_file_signature. Uploads are limited to 30 per hour per source address. Most accounts receive direct: true URLs and never call this route.

Uploads one audio file in a single request and returns a public url you can pass as audio_url to the analysis routes. Send multipart/form-data with the audio in the file part. Audio only: video is refused here, use the presigned upload route instead. The bytes are checked, not the declared type: a file that is not valid audio is refused with 400 invalid_file_signature. The body is read in one piece, so the limit is 100 MiB; larger files, and anything you want to keep in your library, go through the presigned upload route or an upload session.

The file is temporary: it is removed 24 hours after upload. While it exists its size counts toward your storage. url never expires within that time and is the value to use as an audio_url; playback_url is a signed copy for playing the file in a browser and stops working sooner.

This route answers with a bare JSON object: there is no data wrapper, no meta on a success. Uploads are limited to 30 per hour per account and per source address. Available to free and paid accounts.