Media tools

Timeline audio

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

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 (packages/mcp-server/src/mcp.ts). 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 uses a flat number of credits. The API rate card lists the current credits. 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.

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

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 uses a flat number of credits. The API rate card lists the current credits. 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`