Media tools

Audio detach

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

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

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 (packages/mcp-server/src/mcp.ts). 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"
  }'

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