Media tools

Audio detach

Extract the audio track of one Sume-hosted video into a durable wav or mp3. The video is untouched.

Note

Current SoT. Media L2 demux (sume/audio-detach-1.0, #5953). Dest and prod. This is not clip inspection. For clip inspection, use video inspect. For many ranges, detach once. Then split with timeline audio.

Audio detach 1.0 takes one workspace media.sume.com video and returns a new audio artifact. The default is sample-exact wav (pcm_s16le). timeline_create audio.url, POST /v1/timeline-1.0/audio, and speech-to-text use this format. The video does not change. The server compiles ffmpeg on the worker media runtime (apps/api/src/routes.ts createAudioDetachV1 / submitSumeAudioDetachJob).

text

POST /v1/audio-detach
POST /v1/models/sume/audio-detach-1.0/runs   # same body, no extra `model` field

There is no GET /v1/audio-detach/:id. Poll the job envelope:

text

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

Hosted MCP: audio_detach. Writes need idempotency_key (and mcp:write under OAuth). Flow: audio_detach → jobs_wait → jobs_result.

Create a detach

Required: video_url (this workspace’s media.sume.com artifact or asset). The server does not fetch from the open internet. Import the file first (POST /v1/media-imports). Idempotency-Key is required.

Optional: format, range, channels, sample_rate, and the usual mode / webhook_url / wait_timeout_seconds communication fields.

The default mode is async. To wait for a maximum of 30 seconds for a 200 completed job, pass mode: "sync". Otherwise, you get 202 and must poll.

bash

curl -X POST https://api.sume.com/v1/audio-detach \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: audio-detach-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4"
  }'

A successful submit returns a job (request_id is the job id). When result_ready is true, GET /v1/jobs/:id/result is kind: audio_detach and contains audio_url (new artf_), duration_seconds, format, channels, sample_rate (null when omitted, because the value comes from the source), source_duration_seconds, and optional range / warnings[].

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 only worker ffmpeg, with no provider inference.

Program

Field	Effect
`format`	`wav` (default, `pcm_s16le` sample-exact) or `mp3` (128 kbps).
`range`	Optional `{ start, end? }` seconds. Omit it for the whole track. When you omit `end`, the range is open-ended.
`channels`	`source` (default) or `mono`.
`sample_rate`	`16000` \| `44100` \| `48000`. Omit it to inherit the source. `16000` + `channels: "mono"` is the STT shape.

Caps (from packages/api-contract/src/index.ts): source ≤ 1800 s, output ≤ 900 s. A whole track longer than 900 s needs a range.

A source with no audio track fails with detach_source_has_no_audio. First, use video inspect to examine probe.has_audio (frames: false is sufficient).

Refusals (stable codes)

Code	When
`audio_detach_range_empty`	`range.end` ≤ `range.start`, or the range is longer than 900 s.
`detach_source_has_no_audio`	The source has no audio track (worker).
`detach_start_past_source`	`range.start` is more than the probed duration (worker).
`ffmpeg_fields_rejected`	The client sent `af` / `filter` / `ffmpeg` / `cmd` / `codec` / similar fields. The server compiles ffmpeg.
`unsupported_media_source`	`video_url` is not on the Sume media host.
`source_not_found`	A dead `media.sume.com` URL, or one from a different workspace.
`unsupported_media_type`	HEAD is not a video.
`source_duration_exceeded`	The source is longer than 1800 s (worker).

The server rejects off-host URLs (https://example.com/…) at admit. Import the file first.

Not this surface

Need	Use
Probe / stills / optional STT	Video inspect
Exact frame at `t`, source size	Video frames
A new MP4 cut	Video trim
Pixel pass (dim / crop)	Video filter
Many audio ranges from one track	Detach once, then timeline audio `operation: "split"`
Sequence several clips	Timeline 1.0

Media tools

Audio detach

Extract the audio track of one Sume-hosted video into a durable wav or mp3. The video is untouched.

Note

text

POST /v1/audio-detach
POST /v1/models/sume/audio-detach-1.0/runs   # same body, no extra `model` field

There is no GET /v1/audio-detach/:id. Poll the job envelope:

text

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

Hosted MCP: audio_detach. Writes need idempotency_key (and mcp:write under OAuth). Flow: audio_detach → jobs_wait → jobs_result.

Create a detach

Optional: format, range, channels, sample_rate, and the usual mode / webhook_url / wait_timeout_seconds communication fields.

The default mode is async. To wait for a maximum of 30 seconds for a 200 completed job, pass mode: "sync". Otherwise, you get 202 and must poll.

bash

curl -X POST https://api.sume.com/v1/audio-detach \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: audio-detach-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4"
  }'

Program

Field	Effect
`format`	`wav` (default, `pcm_s16le` sample-exact) or `mp3` (128 kbps).
`range`	Optional `{ start, end? }` seconds. Omit it for the whole track. When you omit `end`, the range is open-ended.
`channels`	`source` (default) or `mono`.
`sample_rate`	`16000` \| `44100` \| `48000`. Omit it to inherit the source. `16000` + `channels: "mono"` is the STT shape.

Caps (from packages/api-contract/src/index.ts): source ≤ 1800 s, output ≤ 900 s. A whole track longer than 900 s needs a range.

A source with no audio track fails with detach_source_has_no_audio. First, use video inspect to examine probe.has_audio (frames: false is sufficient).

Refusals (stable codes)

Code	When
`audio_detach_range_empty`	`range.end` ≤ `range.start`, or the range is longer than 900 s.
`detach_source_has_no_audio`	The source has no audio track (worker).
`detach_start_past_source`	`range.start` is more than the probed duration (worker).
`ffmpeg_fields_rejected`	The client sent `af` / `filter` / `ffmpeg` / `cmd` / `codec` / similar fields. The server compiles ffmpeg.
`unsupported_media_source`	`video_url` is not on the Sume media host.
`source_not_found`	A dead `media.sume.com` URL, or one from a different workspace.
`unsupported_media_type`	HEAD is not a video.
`source_duration_exceeded`	The source is longer than 1800 s (worker).

The server rejects off-host URLs (https://example.com/…) at admit. Import the file first.

Not this surface

Need	Use
Probe / stills / optional STT	Video inspect
Exact frame at `t`, source size	Video frames
A new MP4 cut	Video trim
Pixel pass (dim / crop)	Video filter
Many audio ranges from one track	Detach once, then timeline audio `operation: "split"`
Sequence several clips	Timeline 1.0