---
title: 오디오 분리
description: Sume 호스트 비디오 하나의 오디오 트랙을 내구성 wav 또는 mp3로 뽑습니다. 비디오는 건드리지 않습니다.
---

> **현재 SoT.** Media L2 디먹스(`sume/audio-detach-1.0`, #5953). dest와
> prod. **클립 검사가 아닙니다** — 검사는
> [비디오 검사](/models/video-inspect)입니다. 여러 구간이 필요하면
> **한 번** 분리한 뒤 [타임라인 오디오](/models/timeline-audio)로 쪼개세요.

Audio detach 1.0은 워크스페이스의 **하나의** `media.sume.com` 비디오를
받아 **새** 오디오 아티팩트를 반환합니다. 기본은 샘플 정확 wav
(`pcm_s16le`)입니다 — `timeline_create` `audio.url`,
`POST /v1/timeline-1.0/audio`, STT가 원하는 형태입니다. 비디오는
건드리지 않습니다. 서버가 워커 미디어 런타임에서 ffmpeg를
컴파일합니다(`apps/api/src/routes.ts` `createAudioDetachV1` /
`submitSumeAudioDetachJob`).

```text
POST /v1/audio-detach
POST /v1/models/sume/audio-detach-1.0/runs   # 같은 본문, 추가 `model` 필드 없음
```

**`GET /v1/audio-detach/:id`는 없습니다.** Job 봉투로 폴링하세요:

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

호스티드 MCP: `audio_detach`(`packages/mcp-server/src/mcp.ts`). 쓰기는
`idempotency_key`가 필요합니다(OAuth에서는 `mcp:write`). 흐름:
`audio_detach` → `jobs_wait` → `jobs_result`.

## 분리 만들기

필수: `video_url`(이 워크스페이스의 `media.sume.com` 아티팩트 또는
에셋). 공개 인터넷 fetch는 없습니다. 먼저 가져오세요
(`POST /v1/media-imports`). `Idempotency-Key`는 필수입니다.

선택: `format`, `range`, `channels`, `sample_rate`, 평소의 `mode` /
`webhook_url` / `wait_timeout_seconds` 통신 필드입니다.

기본 `mode`는 **`async`**입니다. `mode: "sync"`를 주면 최대 **30초**
기다리고 끝난 Job을 `200`으로 주거나, `202`로 폴링합니다.

```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"
  }'
```

성공한 submit은 Job을 반환합니다(`request_id`가 Job id). `result_ready`이면
`GET /v1/jobs/:id/result`는 `kind: audio_detach`이고 `audio_url`(새
`artf_`), `duration_seconds`, `format`, `channels`, `sample_rate`(생략 시
null — 소스에서 상속), `source_duration_seconds`, 선택적 `range` /
`warnings[]`를 담습니다.

공개 요금: **Job당 $0.01**(`AUDIO_DETACH_PUBLIC_PRICING`; 라이브는
`GET /v1/catalog`). 프로바이더 추론 없음 — 워커 ffmpeg만.

## 프로그램

| 필드 | 효과 |
|---|---|
| `format` | `wav`(기본, `pcm_s16le` 샘플 정확) 또는 `mp3`(128 kbps). |
| `range` | 선택 `{ start, end? }` 초. 생략하면 트랙 전체. `end`를 생략하면 열린 구간. |
| `channels` | `source`(기본) 또는 `mono`. |
| `sample_rate` | `16000` \| `44100` \| `48000`. 생략하면 소스를 상속. `16000` + `channels: "mono"`가 STT 형태. |

상한(`packages/api-contract/src/index.ts`): 소스 ≤ **1800**초; 출력 ≤
**900**초. 트랙 전체가 900초를 넘으면 `range`가 필요합니다.

오디오 트랙이 없는 소스는 `detach_source_has_no_audio`로 실패합니다.
먼저 [비디오 검사](/models/video-inspect)로 `probe.has_audio`를
확인하세요(`frames: false`면 충분).

## 거절(안정 코드)

| 코드 | 언제 |
|---|---|
| `audio_detach_range_empty` | `range.end` ≤ `range.start`, 또는 구간이 900초보다 김. |
| `detach_source_has_no_audio` | 소스에 오디오 트랙이 없음(워커). |
| `detach_start_past_source` | `range.start`가 프로브된 길이보다 뒤(워커). |
| `ffmpeg_fields_rejected` | 클라이언트가 `af` / `filter` / `ffmpeg` / `cmd` / `codec` 등을 보냄. 서버가 ffmpeg를 컴파일합니다. |
| `unsupported_media_source` | `video_url`이 Sume 미디어 호스트가 아님. |
| `source_not_found` | 죽은 또는 다른 워크스페이스 `media.sume.com` URL. |
| `unsupported_media_type` | HEAD가 비디오가 아님. |
| `source_duration_exceeded` | 소스가 1800초보다 김(워커). |

호스트 밖 URL(`https://example.com/…`)은 접수에서 거절됩니다. 먼저
가져오세요.

## 이 표면이 아닌 것

| 필요한 일 | 쓸 것 |
|---|---|
| 프로브 / 스틸 / 선택적 STT | [비디오 검사](/models/video-inspect) |
| `t`의 소스 크기 프레임 | [비디오 프레임](/models/video-frames) |
| 새 MP4 컷 | [비디오 트림](/models/video-trim) |
| 픽셀 패스(dim / crop) | [비디오 필터](/models/video-filter) |
| 한 트랙에서 여러 오디오 구간 | 한 번 분리한 뒤 [타임라인 오디오](/models/timeline-audio) `operation: "split"` |
| 여러 클립 시퀀스 | [Timeline 1.0](/models/timeline) |

## 관련 문서

- [비디오 검사](/models/video-inspect)
- [비디오 프레임](/models/video-frames)
- [비디오 트림](/models/video-trim)
- [비디오 필터](/models/video-filter)
- [Timeline 1.0](/models/timeline)
- [타임라인 오디오](/models/timeline-audio)
- [미디어 입력](/workflows/asset-library)
- [Job과 결과](/workflows/jobs-and-results)
- [MCP 도구와 게이트](/mcp/tools-and-gates)