노이즈 제거 API

노이즈 제거 API는 한 명의 음성에 섞인 지속적인 배경 잡음을 줄이고 MP3 또는 WAV 파일을 반환합니다.

API 한눈에 보기

항목	값
Base URL	https://api.kitschlabs.com
인증	xi-api-key: <API_KEY>
요청	multipart/form-data
Endpoint	POST /v1/audio-isolation
필수 field	audio
기본 출력	mp3_44100_128 (audio/mpeg)
추가 출력	wav_48000 (audio/wav)
최대 입력	50 MiB, 60초

어떻게 인증하나요?

xi-api-key 헤더에 발급받은 API 키를 보냅니다. 실제 키는 서버 환경 변수나 비밀 관리 서비스에 보관하고 브라우저, 앱 번들, 로그에 남기지 마세요.

xi-api-key: <API_KEY>

배경 잡음을 어떻게 줄이나요?

일반 오디오 파일은 file_format=other로 보냅니다. 응답 body를 확장자에 맞는 파일로 저장하세요.

cURL

curl --request POST \
  "https://api.kitschlabs.com/v1/audio-isolation" \
  --header "xi-api-key: <API_KEY>" \
  --form "audio=@sample.wav" \
  --form "file_format=other" \
  --output enhanced.mp3

Python

import os

import requests

with open("sample.wav", "rb") as audio:
    response = requests.post(
        "https://api.kitschlabs.com/v1/audio-isolation",
        headers={"xi-api-key": os.environ["KITSCH_API_KEY"]},
        data={"file_format": "other"},
        files={"audio": audio},
        timeout=120,
    )

response.raise_for_status()

with open("enhanced.mp3", "wb") as output:
    output.write(response.content)

JavaScript

import { readFile, writeFile } from "node:fs/promises";

const form = new FormData();
form.append("audio", new Blob([await readFile("sample.wav")]), "sample.wav");
form.append("file_format", "other");

const response = await fetch("https://api.kitschlabs.com/v1/audio-isolation", {
  method: "POST",
  headers: { "xi-api-key": process.env.KITSCH_API_KEY },
  body: form,
});

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

await writeFile("enhanced.mp3", Buffer.from(await response.arrayBuffer()));

WAV가 필요하면 query에 output_format=wav_48000을 지정합니다.

curl --request POST \
  "https://api.kitschlabs.com/v1/audio-isolation?output_format=wav_48000" \
  --header "xi-api-key: <API_KEY>" \
  --form "audio=@sample.wav" \
  --output enhanced.wav

어떤 필드를 보내나요?

필드	위치	타입	필수	설명
audio	form	file	예	처리할 음성 파일. 최대 50 MiB, 60초
file_format	form	string	아니요	일반 파일은 other, raw PCM은 pcm_s16le_16
output_format	query	string	아니요	mp3_44100_128 또는 wav_48000

pcm_s16le_16은 16 kHz, mono, little-endian 16-bit raw PCM입니다. 일반 WAV, MP3, FLAC, OGG와 같은 encoded audio는 other를 사용하세요.

업로드한 입력 파일은 처리 완료 후 저장하지 않습니다. API 키와 전체 파일 내용을 애플리케이션 로그에 남기지 마세요.

응답과 오류

성공하면 선택한 형식의 audio binary를 반환합니다. 지원 문의에는 응답의 x-kitsch-request-id를 사용할 수 있습니다.

헤더	설명
x-kitsch-request-id	요청 추적 ID

상태 코드	의미	권장 행동
401	API 키가 없거나 유효하지 않음	키와 xi-api-key 헤더 확인
402	사용 가능한 credit 부족	결제 및 청구 상태 확인
403	노이즈 제거 사용 권한 없음	계정의 서비스 이용 범위 확인
413	파일 크기 또는 입력 길이 초과	50 MiB·60초 이내로 줄여 재요청
422	손상된 audio, 잘못된 PCM 또는 지원하지 않는 형식	파일과 file_format 확인
429	API 키 요청 한도 초과	Retry-After를 따르고 backoff 적용
503	일시적으로 처리할 수 없음	request ID를 기록하고 제한적으로 재시도

성공한 요청은 입력 음성 길이를 시작된 1초 단위로 올림해 credit을 계산합니다. 실패하거나 입력 검증에서 거절된 요청은 차감하지 않습니다.