Media tools

Timeline audio

Concat or split Sume-hosted audio into durable media.sume.com files. Sample-domain join, no re-synthesis.

Note

Current SoT. Timeline 1.0 audio (sume/timeline-1.0/audio, #3516). It is available on dest and prod. This job mints a reusable audio file. If you need a join only inside one render, use Timeline 1.0 audio.parts[], and do not use this job.

Timeline audio joins Sume-hosted audio into one gapless file (operation: concat) or slices one file into ranges (operation: split). It returns durable media.sume.com URLs plus timings. The join is sample-domain, with no re-TTS and no silence at the seams. The server compiles ffmpeg on the same worker media runtime as the render (apps/api/src/routes.ts createTimelineV1Audio / submitSumeTimelineAudioJob).

text

POST /v1/timeline-1.0/audio

This surface has no GET /v1/timeline-1.0/audio/:id. Poll the job envelope:

text

GET /v1/jobs/:id/status
GET /v1/jobs/:id/result

The hosted MCP tool is timeline_audio. Writes need idempotency_key (and mcp:write under OAuth). The flow is timeline_audio → jobs_wait → jobs_result.

Concat

The required fields are operation: "concat" and parts[] (1–20, ordered). Each part is { url, source_in?, duration? }. Do not send url or ranges at the top level (audio_concat_takes_no_url / audio_concat_takes_no_ranges).

All URLs must already be this workspace’s media.sume.com audio. Import the files first (POST /v1/media-imports). Idempotency-Key is required.

The default mode is async. To wait up to 30 seconds for a 200 finished job, pass mode: "sync". Otherwise, you get 202. Then poll the job.

bash

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-concat-001" \
  -d '{
    "operation": "concat",
    "parts": [
      { "url": "https://media.sume.com/artifacts/artf_demo/line1.wav" },
      { "url": "https://media.sume.com/artifacts/artf_demo/line2.wav", "source_in": 0.1, "duration": 1.8 }
    ]
  }'

The result is kind: timeline_audio with one audio_url, duration_seconds, and segments[] (index, start, duration_seconds). The segments are the concat offsets that you use to re-base Timeline 1.0 video[].start. Use that file as audio.url on the render, or as Avatar 1.0 image-to-video audio.

All parts must have the same channel layout (audio_parts_channel_mismatch).

Split

The required fields are operation: "split", a top-level url, and ranges[] (1–20). Each range is { start, end? } (if you omit end, the range goes to the end of the file). Do not send parts (audio_split_takes_no_parts). Ranges can overlap.

bash

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 }]
  }'

The result is kind: timeline_audio with segments[], and each segment has its own audio_url. For many ranges from a talking-head MP4, use audio detach one time. Then split the audio here.

Output format

The optional output.format is wav (default, pcm_s16le, sample-exact) or mp3 (smaller, adds priming padding again at every edge). Keep wav if you will join the file again or if the file drives lip-sync.

The produced audio is ≤ 1800 s.

Each job holds the price on the API rate card and is charged the compute it used at list price, idle time included, never more than the hold. The job uses no provider inference, only worker ffmpeg.

Refusals (stable codes)

Code	When
`audio_concat_requires_parts`	Concat without `parts`.
`audio_concat_takes_no_url` / `audio_concat_takes_no_ranges`	Concat plus a split field.
`audio_split_requires_url` / `audio_split_requires_ranges`	Split without `url` or `ranges`.
`audio_split_takes_no_parts`	Split plus `parts`.
`audio_range_end_before_start`	A range `end` ≤ `start`.
`audio_parts_channel_mismatch`	Concat parts do not share a channel layout (worker).
`unsupported_media_source` / `source_not_found`	Off-host or dead URL.
Provider / ffmpeg keys	400 — `filtergraph`, `ffmpeg_args`, `codec`, `crf`, and similar keys.

Sume rejects off-host URLs (https://example.com/…) at admit. Import the files first.

Not this surface

Need	Use
Audio track of one video as wav / mp3	Audio detach
Join only for one render	Timeline 1.0 `audio.parts[]`
Sequence several clips	Timeline 1.0
Still + video in one frame	Timeline compose
Speech-to-text	`POST /v1/stt-1.0/transcribe`

Media tools

Timeline audio

Concat or split Sume-hosted audio into durable media.sume.com files. Sample-domain join, no re-synthesis.

Note

text

POST /v1/timeline-1.0/audio

This surface has no GET /v1/timeline-1.0/audio/:id. Poll the job envelope:

text

GET /v1/jobs/:id/status
GET /v1/jobs/:id/result

The hosted MCP tool is timeline_audio. Writes need idempotency_key (and mcp:write under OAuth). The flow is timeline_audio → jobs_wait → jobs_result.

Concat

All URLs must already be this workspace’s media.sume.com audio. Import the files first (POST /v1/media-imports). Idempotency-Key is required.

The default mode is async. To wait up to 30 seconds for a 200 finished job, pass mode: "sync". Otherwise, you get 202. Then poll the job.

bash

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-concat-001" \
  -d '{
    "operation": "concat",
    "parts": [
      { "url": "https://media.sume.com/artifacts/artf_demo/line1.wav" },
      { "url": "https://media.sume.com/artifacts/artf_demo/line2.wav", "source_in": 0.1, "duration": 1.8 }
    ]
  }'

All parts must have the same channel layout (audio_parts_channel_mismatch).

Split

bash

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 }]
  }'

The result is kind: timeline_audio with segments[], and each segment has its own audio_url. For many ranges from a talking-head MP4, use audio detach one time. Then split the audio here.

Output format

The produced audio is ≤ 1800 s.

Each job holds the price on the API rate card and is charged the compute it used at list price, idle time included, never more than the hold. The job uses no provider inference, only worker ffmpeg.

Refusals (stable codes)

Code	When
`audio_concat_requires_parts`	Concat without `parts`.
`audio_concat_takes_no_url` / `audio_concat_takes_no_ranges`	Concat plus a split field.
`audio_split_requires_url` / `audio_split_requires_ranges`	Split without `url` or `ranges`.
`audio_split_takes_no_parts`	Split plus `parts`.
`audio_range_end_before_start`	A range `end` ≤ `start`.
`audio_parts_channel_mismatch`	Concat parts do not share a channel layout (worker).
`unsupported_media_source` / `source_not_found`	Off-host or dead URL.
Provider / ffmpeg keys	400 — `filtergraph`, `ffmpeg_args`, `codec`, `crf`, and similar keys.

Sume rejects off-host URLs (https://example.com/…) at admit. Import the files first.

Not this surface

Need	Use
Audio track of one video as wav / mp3	Audio detach
Join only for one render	Timeline 1.0 `audio.parts[]`
Sequence several clips	Timeline 1.0
Still + video in one frame	Timeline compose
Speech-to-text	`POST /v1/stt-1.0/transcribe`