Getting started
Limits
Requests, files, sessions and jobs have limits, and going past one returns an error or ends the job.
Request bodies
Request bodies can be at most 1 MiB, or 1,048,576 bytes, on both the API and the MCP server, and the audio you upload doesn't count toward it.
413 Content Too Large
{ "error": { "code": "payload_too_large", "message": "The request body is larger than 1 MiB" }}Files and uploads
| Limit | Value | Beyond it |
|---|---|---|
| File size | 4 GiB (4,294,967,296 bytes) | 400 validation_error when you create the upload: "size_bytes must be between 1 and 4294967296 bytes" |
| File length | At least one second | 422 source_rejected when you complete the upload: "Audio is shorter than one second" |
| Part size | 64 MiB (67,108,864 bytes), with the rest of the file in the last part | The part's URL rejects any other length |
count on POST /v1/uploads/{upload_id}/parts | 1 to 100 | 400 validation_error |
| Upload expiry | 24 hours after creation, with its URLs | 404 not_found "Upload has expired" |
| Source not in a session | Expires 7 days after its upload was completed | We delete it soon after |
Sessions
| Limit | Value | Beyond it |
|---|---|---|
| Length | 1 hour (3600 seconds), measured by the longest source | 400 validation_error: "A session's longest source may be at most 3600 seconds" |
| Microphones | 1 to 4, or none with a mixdown | 422 session_invalid |
| Beds | At most 1, and only with microphones | 422 session_invalid |
| Mixdowns | At most 1, alone in its session | 422 session_invalid |
| Lengths of the microphones and the bed | The same, within 2.7 milliseconds | 422 session_invalid, naming the source furthest off |
label | At most 200 characters | 400 validation_error |
retention_days | 1 to 3650, or none | 400 validation_error |
Jobs
| Limit | Value | Beyond it |
|---|---|---|
| Processing with no progress | 3 hours | The job fails, as described in Jobs |
| Assembling ADM files | 3 hours | The job fails |
| Output download URLs | 24 hours from the request that listed them | List the outputs again for new URLs |
Idempotency-Key | 1 to 128 characters, kept 24 hours | 400 validation_error. After 24 hours, the same key creates a new job. |
Lists and usage
| Limit | Value | Beyond it |
|---|---|---|
limit on GET /v1/sessions and GET /v1/jobs | 1 to 200, 50 by default | 400 validation_error |
Date range of GET /v1/usage | At most 366 days | 400 validation_error |
Queueing
We process a limited number of jobs at a time, so when we're busy a new job waits in queued until there's room for it. You can cancel it until processing starts, and a cancelled job isn't billed.
Polling
Poll a job every few seconds at most, or use webhooks to be told when it ends.