How to split an audio file into parts with an API

To split an audio file into parts, send POST /v1/timeline-1.0/audio with operation: "split", the file's url, and a ranges[] list of { start, end } seconds. Each range comes back as its own durable audio file, and you can send up to 20 ranges in one job.

The fields below are from the Sume docs page Timeline audio, read 2026-09-29.

What does the split request look like?

The url must be audio already in this workspace's media.sume.com space, such as the output of an earlier Sume job. An Idempotency-Key header is required. Leave end off a range to take the rest of the file.

curl -X POST https://api.sume.com/v1/timeline-1.0/audio \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: timeline-audio-split-001" \
  -d '{
    "operation": "split",
    "url": "https://media.sume.com/artifacts/artf_demo/spine.wav",
    "ranges": [{ "start": 0, "end": 12.4 }, { "start": 12.4 }]
  }'

What do I get back?

Poll GET /v1/jobs/:id/status until the job is terminal, then read GET /v1/jobs/:id/result. The result is kind: timeline_audio with segments[], and each segment has its own audio_url. There is no GET-by-id route for this tool, so the job envelope is the only way to read it.

The default output is wav, which is sample-exact. Set output.format to mp3 for smaller files; the docs say mp3 re-adds priming padding at every edge, so keep wav if the parts will be joined again.

How many ranges, and can they overlap?

A job takes 1 to 20 ranges, and ranges may overlap. Produced audio is limited to 1800 seconds. The refusals are stable codes you can branch on.

Should I split by time or by silence?

This tool cuts at the times you send: a range is a start and an optional end, and the docs describe no other way to choose a boundary. Find the boundaries first, for example from the word timings in a transcript, and pass them as start and end. Because ranges may overlap, you can leave a short lead-in before each boundary without cutting the previous part. Each returned segment is a separate file, so you can send the parts to other tools one by one.

What if the audio is inside a video?

Detach it first. Audio detach turns one video's track into a wav or mp3, and the docs say to detach once and then split with Timeline audio when you need many ranges from one track.