DIVE Standard API

URL

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

인증 및 헤더

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

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

목소리 선택 방법

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

요청 필드

• textstring | string[]필수

  합성할 텍스트입니다. 배열이면 순서대로 이어서 처리합니다.

  계정별 최대 길이 적용; 별도 설정이 없으면 500 UTF-16 code unit

• mode"preset" | "saved"선택

  목소리 선택 방법입니다. preset은 voiceName과 emotion을, saved는 savedVoiceId 또는 referenceTokens를 사용합니다.

  기본값 "preset"

• langstring선택

  합성 언어 코드입니다.

  기본값 "ko"

• outputFormatstring선택

  오디오 포맷입니다. 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"

• rawDataboolean선택

  true면 JSON 대신 선택한 포맷의 오디오 바이트를 직접 반환합니다.

  기본값 false

• enableTimestampsboolean선택

  권한이 있는 계정에서 타임스탬프 배열을 JSON 응답에 포함합니다.

  기본값 false

• speednumber선택

  재생 속도입니다. 범위를 벗어나면 서버가 보정합니다.

  기본값 1 · 0.5–2.0

• pitchnumber선택

  피치 조절값입니다. 범위를 벗어나면 서버가 보정합니다.

  기본값 0 · -6–6

• volumenumber선택

  출력 볼륨입니다. 범위를 벗어나면 서버가 허용 범위로 보정합니다.

  기본값 50 · 1–100

• sentenceSilenceSecnumber선택

  텍스트를 문장 단위로 나눈 뒤, 완성된 문장 오디오 사이에 직접 삽입하는 무음 길이(초)입니다.

  기본값 0.4 · 0.1–2.0

• dictionaryIdUUID선택

  합성 전에 적용할 조직 소유 단어장 ID입니다.

• priorityboolean선택

  우선 처리 권한이 있는 계정에서만 사용할 수 있습니다.

  기본값 false

• voiceNamestring조건부

  mode가 preset일 때 사용할 프리셋 목소리 이름입니다.

  mode=preset이면 필수

• emotionstring조건부

  voiceName이 지원하는 감정 이름입니다.

  mode=preset이면 필수

• savedVoiceIdUUID조건부

  mode가 saved일 때 등록된 목소리 ID입니다.

  mode=saved에서 referenceTokens가 없으면 필수

• referenceTokensnumber[] | object조건부

  저장 ID 없이 합성할 참조 토큰입니다. 숫자 배열 또는 { ko?: number[], en?: number[] } 객체를 받습니다.

  mode=saved에서 savedVoiceId가 없으면 필수

요청 예시

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

응답

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

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

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