DIVE · Streaming

DIVE Streaming API

합성되는 오디오를 HTTP chunked response로 바로 받아 재생합니다.

스트리밍 음성 합성

첫 오디오부터 순서대로 전달되는 바이너리 응답입니다.

URL

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

인증 및 헤더

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	선택	스트리밍 오디오 포맷입니다. 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 기본값 "mp3_48000_128"
`volume`	number	선택	출력 볼륨입니다. 범위를 벗어나면 서버가 허용 범위로 보정합니다. 기본값 50 · 1–100
`sentenceSilenceSec`	number	선택	Gateway가 전달한 문장 순번을 바탕으로 DIVE 엔진이 두 번째 이후 문장 스트림 앞에 삽입하는 무음 길이(초)입니다. 기본값 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": "mp3_48000_128"
}

응답

200

오디오 스트림

응답 body는 선택한 코덱의 오디오 바이트입니다. 도착 순서대로 연결합니다.

Response headers

Content-Type: 요청 포맷에 대응하는 audio/*
Transfer-Encoding: chunked
X-Prosody-Output-Format: {OUTPUT_FORMAT}
X-Prosody-Declared-Content-Type: 요청 포맷에 대응하는 audio/*
Cache-Control: no-cache
X-Accel-Buffering: no

4xx/5xx

스트림 시작 전 오류

응답이 시작되기 전 오류는 DIVE 공통 JSON 오류 형식으로 반환됩니다.

스트림 시작 전 오류

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

요청 body는 최대 10 MiB입니다.
dictionaryId가 UUID 형식이 아니거나 조직에서 찾을 수 없으면 원문으로 합성하지 않고 E4301/404를 반환합니다.
단어장 DB/RPC 조회를 일시적으로 사용할 수 없으면 E5002/503을 반환합니다.
Streaming에서는 speed, pitch, rawData, enableTimestamps를 처리하지 않습니다.
outputFormat에 wav 계열을 보내면 지원 포맷이 아니므로 기본값 mp3_48000_128로 정규화됩니다.