저장한 목소리 API
사전 승인을 받은 조직이 한국어·영어 음성 샘플을 등록하고 DIVE saved 모드에서 재사용합니다.
목소리 등록
multipart/form-data로 한 언어 이상의 음성과 정확한 발화문을 전송합니다. 조직에 저장 목소리 사전 승인이 없으면 E4101/403입니다.
URL
https://agitvxptajouhvoatxio.supabase.co/functions/v1/register-dive-voice-v1인증 및 헤더
API Key는 서버 환경변수에 보관하고 요청 헤더로만 전달하세요.
X-API-Key: {YOUR_API_KEY}
Content-Type: multipart/form-data; boundary=...요청 필드
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
name | string | 필수 | 저장할 목소리 이름입니다. 최대 50자 |
description | string | 선택 | 목소리 설명입니다. 최대 200자 |
audioFileKo | File | 조건부 | 한국어 음성 파일입니다. audioFileEn이 없으면 필수 |
audioTextKo | string | 조건부 | 한국어 파일의 정확한 발화문입니다. audioFileKo와 한 쌍; 한글 포함 필수 |
audioFileEn | File | 조건부 | 영어 음성 파일입니다. audioFileKo가 없으면 필수 |
audioTextEn | string | 조건부 | 영어 파일의 정확한 발화문입니다. audioFileEn과 한 쌍; 한글 포함 불가 |
요청 예시
curl -X POST "https://agitvxptajouhvoatxio.supabase.co/functions/v1/register-dive-voice-v1" \
-H "X-API-Key: {YOUR_API_KEY}" \
-F "name=고객 안내 음성" \
-F "audioFileKo=@voice-ko.wav" \
-F "audioTextKo=안녕하세요. 고객 안내 음성입니다."응답
등록 결과
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
id | UUID | 필수 | 생성된 목소리 ID입니다. |
name | string | 필수 | 저장된 이름입니다. |
status | "completed" | 필수 | 요청한 언어가 둘이면 하나 이상의 참조 토큰 생성이 성공한 상태입니다. 두 언어 모두 성공했다는 뜻은 아닙니다. |
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "고객 안내 음성",
"status": "completed"
}E4201 / E4203 · 입력 또는 오디오 오류
multipart 필드가 빠졌거나 언어 텍스트가 잘못되었거나, 파일을 읽은 결과 길이가 2–20초 범위를 벗어난 경우입니다.
E4101 · 사전 승인 필요
조직에 저장 목소리 기능 권한이 없습니다.
E5002 · 참조 파일 Storage 일시 불가
요청한 참조 파일 업로드가 실패했습니다. completed를 반환하지 않으며 생성된 행과 Storage prefix를 보상 정리합니다. Storage 정리까지 실패하면 추적 가능한 failed 행을 유지합니다.
- 인식하는 파일 확장자는 wav, mp3, m4a, webm, ogg, flac이며 각 음성은 2–20초여야 합니다.
- multipart 요청과 업로드한 음성 파일의 합계는 각각 최대 50 MiB입니다.
- 모든 업로드 파일의 길이 검증이 끝난 뒤에만 DB 레코드와 Storage 객체를 만듭니다. 검증 실패는 부분 레코드나 파일을 남기지 않습니다.
- 한국어와 영어를 함께 요청했을 때 한 언어만 토큰 생성에 성공해도 현재 status는 completed입니다. 응답에는 언어별 실패 사유가 없고, 목록의 englishAvailable로 영어 사용 가능 여부만 확인할 수 있습니다. 한국어 사용 가능 여부는 별도 필드로 제공되지 않습니다.
- 한국어만 등록하면 영어 생성이 백그라운드에서 시도되므로 completed 직후 englishAvailable은 false일 수 있고, 백그라운드 실패도 등록 응답에는 추가되지 않습니다.
- audioFile/audioText 레거시 필드도 지원하지만 새 연동은 언어별 필드를 사용하세요.
목소리 목록
조직의 저장된 목소리를 최신순으로 조회합니다.
URL
https://agitvxptajouhvoatxio.supabase.co/functions/v1/list-dive-voices-v1인증 및 헤더
API Key는 서버 환경변수에 보관하고 요청 헤더로만 전달하세요.
X-API-Key: {YOUR_API_KEY}응답
목록 응답
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
voices | object[] | 필수 | id, name, description, englishAvailable, usageCount, status, createdAt 목록입니다. |
{
"voices": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "고객 안내 음성",
"description": null,
"englishAvailable": false,
"usageCount": 0,
"status": "completed",
"createdAt": "2026-07-28T00:00:00.000Z"
}
]
}목소리 삭제
조직이 소유한 목소리와 저장된 참조 파일을 삭제합니다.
URL
https://agitvxptajouhvoatxio.supabase.co/functions/v1/delete-dive-voice-v1/{id}인증 및 헤더
API Key는 서버 환경변수에 보관하고 요청 헤더로만 전달하세요.
X-API-Key: {YOUR_API_KEY}경로 파라미터
| 필드 | 타입 | 필수 여부 | 설명 |
|---|---|---|---|
id | UUID | 필수 | 삭제할 저장 목소리 ID입니다. |
응답
삭제 완료
응답 body는 비어 있습니다.
E5001 · Storage 또는 DB 정리 실패
Storage 목록 조회·삭제나 DB 삭제가 실패했습니다. Storage 정리 실패 시 DB 레코드는 유지됩니다.
- Storage 객체를 1,000개씩 반복 조회·삭제하고 각 결과를 확인한 뒤에만 DB 레코드를 삭제합니다. Storage 정리에 실패하면 E5001을 반환하며 레코드는 유지됩니다.