관리 · 목소리

저장한 목소리 API

사전 승인을 받은 조직이 한국어·영어 음성 샘플을 등록하고 DIVE saved 모드에서 재사용합니다.

목소리 등록

multipart/form-data로 한 언어 이상의 음성과 정확한 발화문을 전송합니다. 조직에 저장 목소리 사전 승인이 없으면 E4101/403입니다.

URL

POST

https://agitvxptajouhvoatxio.supabase.co/functions/v1/register-dive-voice-v1

인증 및 헤더

API Key는 서버 환경변수에 보관하고 요청 헤더로만 전달하세요.

http

X-API-Key: {YOUR_API_KEY}
Content-Type: multipart/form-data; boundary=...

요청 필드

namestring필수
저장할 목소리 이름입니다.
최대 50자
descriptionstring선택
목소리 설명입니다.
최대 200자
audioFileKoFile조건부
한국어 음성 파일입니다.
audioFileEn이 없으면 필수
audioTextKostring조건부
한국어 파일의 정확한 발화문입니다.
audioFileKo와 한 쌍; 한글 포함 필수
audioFileEnFile조건부
영어 음성 파일입니다.
audioFileKo가 없으면 필수
audioTextEnstring조건부
영어 파일의 정확한 발화문입니다.
audioFileEn과 한 쌍; 한글 포함 불가

목소리 등록 요청 필드
필드	타입	필수 여부	설명
`name`	string	필수	저장할 목소리 이름입니다. 최대 50자
`description`	string	선택	목소리 설명입니다. 최대 200자
`audioFileKo`	File	조건부	한국어 음성 파일입니다. audioFileEn이 없으면 필수
`audioTextKo`	string	조건부	한국어 파일의 정확한 발화문입니다. audioFileKo와 한 쌍; 한글 포함 필수
`audioFileEn`	File	조건부	영어 음성 파일입니다. audioFileKo가 없으면 필수
`audioTextEn`	string	조건부	영어 파일의 정확한 발화문입니다. audioFileEn과 한 쌍; 한글 포함 불가

요청 예시

bash

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=안녕하세요. 고객 안내 음성입니다."

응답

201

등록 결과

idUUID필수
생성된 목소리 ID입니다.
namestring필수
저장된 이름입니다.
status"completed"필수
요청한 언어가 둘이면 하나 이상의 참조 토큰 생성이 성공한 상태입니다. 두 언어 모두 성공했다는 뜻은 아닙니다.

목소리 등록 등록 결과 응답 필드
필드	타입	필수 여부	설명
`id`	UUID	필수	생성된 목소리 ID입니다.
`name`	string	필수	저장된 이름입니다.
`status`	"completed"	필수	요청한 언어가 둘이면 하나 이상의 참조 토큰 생성이 성공한 상태입니다. 두 언어 모두 성공했다는 뜻은 아닙니다.

등록 결과

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "고객 안내 음성",
  "status": "completed"
}

400

E4201 / E4203 · 입력 또는 오디오 오류

multipart 필드가 빠졌거나 언어 텍스트가 잘못되었거나, 파일을 읽은 결과 길이가 2–20초 범위를 벗어난 경우입니다.

403

E4101 · 사전 승인 필요

조직에 저장 목소리 기능 권한이 없습니다.

503

E5002 · 음성 파일 저장 일시 불가

업로드한 음성 파일을 저장하지 못했습니다. completed를 반환하지 않으며, 이 요청으로 만든 목소리와 파일을 정리합니다. 파일 정리까지 실패하면 목소리는 failed 상태로 남습니다.

인식하는 파일 확장자는 wav, mp3, m4a, webm, ogg, flac이며 각 음성은 2–20초여야 합니다.
multipart 요청과 업로드한 음성 파일의 합계는 각각 최대 50 MiB입니다.
모든 업로드 파일의 길이 검증이 끝난 뒤에만 목소리와 파일을 저장합니다. 검증에 실패하면 목소리나 파일이 남지 않습니다.
한국어와 영어를 함께 요청했을 때 한 언어만 토큰 생성에 성공해도 현재 status는 completed입니다. 응답에는 언어별 실패 사유가 없고, 목록의 englishAvailable로 영어 사용 가능 여부만 확인할 수 있습니다. 한국어 사용 가능 여부는 별도 필드로 제공되지 않습니다.
한국어만 등록하면 영어 생성이 백그라운드에서 시도되므로 completed 직후 englishAvailable은 false일 수 있고, 백그라운드 실패도 등록 응답에는 추가되지 않습니다.
audioFile/audioText 레거시 필드도 지원하지만 새 연동은 언어별 필드를 사용하세요.

목소리 목록

조직의 저장된 목소리를 최신순으로 조회합니다.

URL

GET

https://agitvxptajouhvoatxio.supabase.co/functions/v1/list-dive-voices-v1

인증 및 헤더

API Key는 서버 환경변수에 보관하고 요청 헤더로만 전달하세요.

http

X-API-Key: {YOUR_API_KEY}

응답

200

목록 응답

voicesobject[]필수
id, name, description, englishAvailable, usageCount, status, createdAt 목록입니다.

목소리 목록 목록 응답 응답 필드
필드	타입	필수 여부	설명
`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

DELETE

https://agitvxptajouhvoatxio.supabase.co/functions/v1/delete-dive-voice-v1/{id}

인증 및 헤더

API Key는 서버 환경변수에 보관하고 요청 헤더로만 전달하세요.

http

X-API-Key: {YOUR_API_KEY}

경로 파라미터

idUUID필수
삭제할 저장 목소리 ID입니다.

목소리 삭제 경로 파라미터
필드	타입	필수 여부	설명
`id`	UUID	필수	삭제할 저장 목소리 ID입니다.

응답

200

삭제 완료

응답 body는 비어 있습니다.

500

E5001 · 목소리 삭제 실패

저장된 음성 파일이나 목소리를 삭제하지 못했습니다. 파일 삭제에 실패하면 목소리는 삭제되지 않고 유지됩니다.

저장된 음성 파일을 모두 삭제한 뒤에만 목소리를 삭제합니다. 파일 삭제에 실패하면 E5001을 반환하며 목소리는 유지됩니다.