DIVE · Standard

DIVE Standard API

텍스트 전체를 합성한 뒤 오디오 URL 또는 오디오 바이트로 반환합니다.

음성 합성

완료된 합성 결과가 필요할 때 사용합니다.

URL

POSThttps://api-console.humelo.net/api/v1/dive

인증 및 헤더

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

X-API-Key: {YOUR_API_KEY}
Content-Type: application/json

목소리 선택 방법

한 요청에서는 아래 세 가지 중 하나만 선택하세요. 프리셋 목소리를 사용할 때만 mode를 생략할 수 있습니다.

프리셋 목소리

기본

mode: "preset"

Humelo가 제공하는 목소리 이름과 지원 감정을 선택합니다.

함께 보낼 필드voiceNameemotion

저장된 목소리

mode: "saved"

목소리 등록 API로 만든 저장 목소리 ID를 사용합니다.

함께 보낼 필드savedVoiceId

참조 토큰 직접 전달

mode: "saved"

저장 목소리 ID 대신 참조 토큰을 요청에 직접 넣습니다.

함께 보낼 필드referenceTokens

요청 필드

음성 합성 요청 필드
필드	타입	필수 여부	설명
`text`	string \| string[]	필수	합성할 텍스트입니다. 배열이면 순서대로 이어서 처리합니다. 계정별 최대 길이 적용; 별도 설정이 없으면 500 UTF-16 code unit
`mode`	"preset" \| "saved"	선택	목소리 선택 방법입니다. preset은 voiceName과 emotion을, saved는 savedVoiceId 또는 referenceTokens를 사용합니다. 기본값 "preset"
`lang`	string	선택	합성 언어 코드입니다. 기본값 "ko"
`outputFormat`	string	선택	오디오 포맷입니다. wav_8000, wav_16000, wav_24000, wav_48000, pcm_8000, pcm_16000, pcm_24000, pcm_48000, opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, mp3_22050_48, mp3_24000_64, mp3_44100_96, mp3_48000_128, aac_48000_128, alaw_8000, ulaw_8000 기본값 "wav_48000"
`rawData`	boolean	선택	true면 JSON 대신 선택한 포맷의 오디오 바이트를 직접 반환합니다. 기본값 false
`enableTimestamps`	boolean	선택	권한이 있는 계정에서 타임스탬프 배열을 JSON 응답에 포함합니다. 기본값 false
`speed`	number	선택	재생 속도입니다. 범위를 벗어나면 서버가 보정합니다. 기본값 1 · 0.5–2.0
`pitch`	number	선택	피치 조절값입니다. 범위를 벗어나면 서버가 보정합니다. 기본값 0 · -6–6
`volume`	number	선택	출력 볼륨입니다. 범위를 벗어나면 서버가 허용 범위로 보정합니다. 기본값 50 · 1–100
`sentenceSilenceSec`	number	선택	Gateway가 텍스트를 여러 문장으로 나눈 뒤, 완성된 문장 오디오 사이에 직접 삽입하는 무음 길이(초)입니다. 기본값 0.4 · 0.1–2.0
`dictionaryId`	UUID	선택	합성 전에 적용할 조직 소유 단어장 ID입니다.
`priority`	boolean	선택	우선 처리 권한이 있는 계정에서만 사용할 수 있습니다. 기본값 false
`voiceName`	string	조건부	`mode`가 `preset`일 때 사용할 프리셋 목소리 이름입니다. mode=preset이면 필수
`emotion`	string	조건부	`voiceName`이 지원하는 감정 이름입니다. mode=preset이면 필수
`savedVoiceId`	UUID	조건부	`mode`가 `saved`일 때 등록된 목소리 ID입니다. mode=saved에서 referenceTokens가 없으면 필수
`referenceTokens`	number[] \| object	조건부	저장 ID 없이 합성할 참조 토큰입니다. 숫자 배열 또는 `{ ko?: number[], en?: number[] }` 객체를 받습니다. mode=saved에서 savedVoiceId가 없으면 필수

요청 예시

{
  "text": "안녕하세요. DIVE 음성 합성 테스트입니다.",
  "mode": "preset",
  "voiceName": "시아",
  "emotion": "neutral",
  "lang": "ko",
  "outputFormat": "wav_48000"
}

응답

200

JSON 응답

기본 응답입니다. `enableTimestamps`가 승인되면 timestamps가 추가될 수 있습니다.

음성 합성 JSON 응답 응답 필드
필드	타입	필수 여부	설명
`jobId`	UUID	필수	생성된 합성 작업 ID입니다.
`audioUrl`	string	필수	완성된 오디오의 공개 URL입니다.
`outputFormat`	string	필수	실제로 적용된 출력 포맷입니다.
`timestamps`	object[]	조건부	타임스탬프 권한이 있고 결과가 존재할 때만 포함됩니다.

JSON 응답

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "audioUrl": "https://cdn.example.com/output/audio.wav",
  "outputFormat": "wav_48000"
}

200

오디오 바이트 응답

`rawData: true`일 때 JSON 대신 오디오 바이트를 반환합니다.

Response headers

Content-Type: 요청 포맷에 대응하는 audio/*
X-Prosody-Job-Id: {JOB_ID}
X-Prosody-Output-Format: {OUTPUT_FORMAT}

4xx/5xx

오류 응답

{
  "error": {
    "code": "E4201",
    "message": "Invalid request",
    "details": "Missing required field: text"
  }
}

요청 body는 최대 4 MiB입니다.
dictionaryId가 UUID 형식이 아니거나 조직에서 찾을 수 없으면 원문으로 합성하지 않고 E4301/404를 반환합니다.
단어장 DB/RPC 조회를 일시적으로 사용할 수 없으면 E5002/503을 반환합니다. 이 경우 backoff 후 제한적으로 재시도할 수 있습니다.
outputFormat에 알 수 없는 값이 들어오면 오류 대신 기본 포맷 wav_48000으로 정규화됩니다.
settings.speed, settings.pitch, settings.volume도 호환되지만 새 연동은 최상위 speed, pitch, volume을 사용하세요.
기존 Supabase /functions/v1/dive-synthesize-v1 URL은 이 Standard API로 전달되는 호환 경로입니다. dive-synthesize-v2는 별도 모델용 API이며 v1 또는 Gateway Standard의 자동 대체·폐기 경로가 아닙니다.