# Prosody Console Documentation

> Documentation index for Prosody AICC, DIVE, FRTTS, STT, API keys, and error handling.
> Fetch the complete documentation bundle at:
> https://console.humelo.com/llms-full.txt

Use the Markdown links below when giving Prosody documentation to ChatGPT, Claude, Codex, Cursor, or another coding agent.

## Getting Started

- [Overview and API Keys](https://console.humelo.com/docs-md/overview): API key issuance, authentication headers, response format, and common HTTP status codes.

## AICC

- [AICC API and Web Integration](https://console.humelo.com/docs-md/aicc): Attach a custom AICC to your product with server-side API calls, streaming, state, handoff, and widget patterns.

## Agent

- [Web Widget](https://console.humelo.com/docs-md/web-widget): Install the Prosody agent widget on a website, configure allowed domains, and subscribe to client events.
- [Service Integrations](https://console.humelo.com/docs-md/service-integrations): Configure the available Slack integration and review enterprise-only integration options.

## Speech Synthesis

- [DIVE Standard API](https://console.humelo.com/docs-md/dive): Generate high-quality speech from text with the DIVE synthesis endpoint.
- [DIVE Streaming API](https://console.humelo.com/docs-md/dive-streaming): Stream DIVE audio chunks for low-latency playback.
- [DIVE WebSocket API](https://console.humelo.com/docs-md/dive-websocket): Reuse one WebSocket connection for sequential DIVE synthesis requests with explicit lifecycle events.
- [Saved Voices](https://console.humelo.com/docs-md/saved-voices): Manage saved custom voices for synthesis workflows.
- [FRTTS API](https://console.humelo.com/docs-md/frtts): Generate speech with FRTTS request examples and response format.

## Speech Recognition

- [STT API](https://console.humelo.com/docs-md/stt): Transcribe audio files or audio payloads into text.

## Utilities

- [Dictionaries](https://console.humelo.com/docs-md/dictionaries): Manage pronunciation and recognition dictionaries for domain-specific words.

## Reference

- [Error Codes](https://console.humelo.com/docs-md/error-codes): Shared HTTP status codes, error response format, and recommended retry behavior.

---
url: https://console.humelo.com/docs
markdown: https://console.humelo.com/docs-md/overview
title: Overview and API Keys
category: Getting Started
---

# Prosody API Overview

Prosody Console provides API keys for AICC, DIVE, FRTTS, and STT integrations.

## API Keys

Create keys in Console > API Key. Store the plain key immediately because it is only shown once when the key is created and cannot be retrieved again.

## Authentication

Voice APIs use `X-API-Key: your_api_key_here`. AICC runtime uses `Authorization: Bearer your_api_key_here`.

## Error Format

Voice APIs:

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

AICC runtime keeps a flat compatibility shape with the same common code values:

```json
{
  "error": "message or a user message in history is required",
  "code": "E4201"
}
```

## Important Pages

- /docs/aicc for AICC API and web widget integration.
- /docs/web-widget for browser widget installation and events.
- /docs/service-integrations for the available Slack integration and enterprise inquiry options.
- /docs/dive, /docs/dive-streaming, and /docs/dive-websocket for DIVE speech synthesis.
- /docs/frtts for FRTTS.
- /docs/stt for speech recognition.
- /docs/error-codes for shared error handling.

---
url: https://console.humelo.com/docs/aicc
markdown: https://console.humelo.com/docs-md/aicc
title: AICC API and Web Integration
category: AICC
---

# AICC Runtime API

게시한 에이전트에 사용자 메시지와 최근 대화 상태를 전달하고 JSON 또는 SSE로 답변을 받습니다.

## 에이전트 대화

API Key와 Agent ID는 서버에만 보관하고 브라우저에서는 고객 서버 프록시를 호출하세요.

```http
POST https://console.humelo.com/api/v1/agents/chat
```

### 인증 및 헤더

```http
Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json
Accept: application/json # SSE는 text/event-stream
```

### 요청 필드

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `agent_id` | UUID | 필수 | - | 호출할 에이전트 ID입니다. Agent Builder에서 확인할 수 있습니다. |
| `message` | string | 조건부 | - | 이번 턴의 사용자 입력입니다. 생략하거나 공백이면 history 또는 messages의 마지막 비어 있지 않은 user 메시지를 사용합니다. 대체할 user 메시지가 없으면 E4201/400; 최대 4,000자 |
| `session_id` | string | 선택 | - | 운영 로그에서 같은 상담을 묶을 고객 측 세션 ID입니다. 영문, 숫자, `.`, `_`, `:`, `-`만 사용; 1–160자 |
| `history` | Turn[] | 선택 | [] | 최근 대화입니다. 각 항목은 role과 content를 가지며 messages보다 우선합니다. 마지막 16턴 사용; role은 user 또는 assistant; content는 턴당 최대 4,000자 |
| `messages` | Turn[] | 선택 | [] | history와 같은 형식의 별칭입니다. history가 없을 때만 사용됩니다. 마지막 16턴 사용 |
| `state` | object \| null | 선택 | null | 이전 응답의 state를 그대로 전달하면 멀티턴 상태가 이어집니다. JSON 문자열 기준 최대 16,000자 |
| `stream` | boolean | 선택 | false | true면 Server-Sent Events로 응답합니다. Accept 헤더로도 활성화할 수 있습니다. |

### 요청 예시

```json
{
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "message": "예약 취소 수수료가 어떻게 되나요?",
  "session_id": "customer-42:chat-7",
  "history": [],
  "state": null,
  "stream": false
}
```

### 응답

#### 200 · JSON 응답

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `agent_id` | UUID | 필수 | - | 응답한 에이전트 ID입니다. |
| `agent_name` | string | 필수 | - | 에이전트 이름입니다. |
| `response` | string | 필수 | - | 최종 답변입니다. |
| `matched_intent` | string \| null | 필수 | - | 매칭된 의도 이름입니다. |
| `handoff_required` | boolean | 필수 | - | 상담원 연결이 필요한지 나타냅니다. |
| `retrieved_context` | object[] | 필수 | - | 답변에 사용한 지식 항목입니다. |
| `actions` | object[] | 필수 | - | 실행한 에이전트 액션입니다. |
| `state` | object | 필수 | - | 다음 요청에 다시 보낼 멀티턴 상태입니다. |
| `end_call` | boolean | 필수 | - | 음성 채널에서 통화 종료가 필요한지 나타냅니다. |
| `runtime` | object | 필수 | - | 응답 채널 메타데이터입니다. |

```json
{
  "agent_id": "00000000-0000-0000-0000-000000000000",
  "agent_name": "라온투어 고객센터",
  "response": "예약 조건에 따라 취소 수수료가 달라질 수 있습니다.",
  "matched_intent": "패키지 취소료 기준",
  "handoff_required": false,
  "retrieved_context": [],
  "actions": [],
  "state": { "topic": "cancellation_fee", "handoff": false },
  "end_call": false,
  "runtime": { "mode": "text", "voice_engine": "DIVE" }
}
```

#### 200 · SSE 응답

stream이 true이거나 Accept가 text/event-stream이면 start, chunk, 선택적인 tool_call, done 순서로 전송됩니다. 실패 시 error 이벤트로 종료됩니다.

```http
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache, no-transform
X-Accel-Buffering: no
```

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `start` | event | 필수 | - | 의도, 핸드오프, 검색 지식, 초기 state입니다. |
| `chunk` | event | 필수 | - | 화면에 이어 붙일 delta 문자열입니다. |
| `tool_call` | event | 선택 | - | 도구 실행이 공개될 때의 이름과 인자입니다. |
| `done` | event | 필수 | - | 사용량 정산까지 성공한 뒤 보내는 최종 response, actions, state, end_call입니다. |
| `error` | event | 조건부 | - | 스트림 처리 실패 시 오류 메시지입니다. |

#### 400 · E4201 · 잘못된 요청

agent_id가 없거나, message와 history/messages의 user 입력이 모두 비어 있거나, 필드 형식이 잘못된 경우입니다. 예약·과금·provider 호출 전에 거절됩니다.

```json
{
  "error": "message or a user message in history is required",
  "code": "E4201"
}
```

#### 401 · E4001 / E4002 · 인증 오류

Bearer API Key가 없거나 유효하지 않습니다.

#### 402 · E4601 · 크레딧 부족

최대 예상 사용량을 예약할 크레딧이 부족합니다.

#### 404 · E4301 · 에이전트 없음

API Key 조직에서 agent_id를 찾을 수 없습니다.

#### 409 · E4302 · 게시 버전 없음

에이전트에 사용할 수 있는 게시 버전이 없습니다.

#### 413 · E4204 · 요청 크기 초과

요청 body 또는 state가 허용 크기를 초과했습니다.

#### 429 · E4403 · 호출 제한 초과

API Key 기준 분당 60회 제한을 초과했습니다.

#### 500 / 503 · E5001 / E5002 · 서버 또는 일시적 서비스 오류

E5002는 backoff 후 제한적으로 재시도할 수 있습니다. 실패한 요청의 최대 예약분은 정산 전에 환급되며, SSE는 정산 실패 시 done 대신 error 이벤트로 종료됩니다.

### 주의사항

- 요청 body는 최대 64,000 bytes이며 API Key별 호출 제한은 분당 60회입니다.
- message와 각 history content는 앞뒤 공백을 제거한 뒤 최대 길이까지만 사용합니다.
- message와 history/messages의 user 입력이 모두 비어 있으면 E4201/400이며 사용량 예약, provider 호출, 런타임 로그가 발생하지 않습니다.
- session_id가 허용 패턴과 맞지 않으면 요청은 처리되지만 세션 ID는 기록되지 않습니다.

## Next.js Server Proxy

Use this shape when you want a ChannelTalk-style widget on your website. The browser talks to your backend. Your backend calls Prosody.

```ts
// app/api/agent/chat/route.ts
export async function POST(request: Request) {
  const body = await request.json();

  const response = await fetch("https://console.humelo.com/api/v1/agents/chat", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.PROSODY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: process.env.PROSODY_AGENT_ID,
      message: body.message,
      history: body.history ?? [],
      state: body.state ?? null,
      stream: false,
    }),
  });

  return new Response(await response.text(), {
    status: response.status,
    headers: { "Content-Type": response.headers.get("Content-Type") ?? "application/json" },
  });
}
```

## Browser Widget Pattern

A production widget usually needs four pieces:

1. A launcher button fixed to the bottom corner.
2. A chat panel that stores local draft messages.
3. A server-side proxy endpoint.
4. A small session store that preserves `history` and Prosody `state`.

Minimal client shape:

```ts
type Turn = { role: "user" | "assistant"; content: string };

let history: Turn[] = [];
let state: Record<string, unknown> | null = null;

async function sendToAgent(message: string) {
  const response = await fetch("/api/agent/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message, history, state }),
  });

  if (!response.ok) {
    throw new Error("Agent is temporarily unavailable");
  }

  const result = await response.json();
  history = [
    ...history,
    { role: "user", content: message },
    { role: "assistant", content: result.response },
  ].slice(-16);
  state = result.state ?? state;
  return result;
}
```

## Multi-Turn Rules

Prosody does not require you to resend the full conversation forever. Send a short recent history window and the returned `state`. The state is designed to preserve compact task context such as current topic, handoff flow, and useful runtime hints.

Recommended defaults:

- Keep the last 8 to 16 turns in `history`.
- Persist `state` per user conversation.
- Start a new state when the user intentionally starts a new support session.
- Do not include sensitive internal notes that should not be used by the agent.

## Handoff Handling

If `handoff_required` is `true`, show a human-support path. You can still display `response`; it is written to explain what information is needed before escalation.

```ts
if (result.handoff_required) {
  openHumanSupport({
    transcript: history,
    state: result.state,
    matchedIntent: result.matched_intent,
  });
}
```

## Security Checklist

- Keep `PROSODY_API_KEY` on the server only.
- Restrict your proxy with your own session, origin, or rate limit policy.
- Never put the API key in a script tag, public environment variable, or mobile bundle.
- Log Prosody request IDs or your own correlation IDs for support.
- Redact PII before storing transcripts if your policy requires it.

## Error Handling

| Status | Meaning | Recommended handling |
| --- | --- | --- |
| 400 | Missing or malformed request | Fix request shape before retrying. |
| 401 | Invalid API key | Rotate or reconfigure the key. |
| 402 | Insufficient credits | Add credits before retrying. |
| 404 | AICC not found or not owned by the API key organization | Check `agent_id` and organization ownership. |
| 409 | No published agent version | Publish a version before retrying. |
| 413 | Request body or state too large | Reduce the request size. |
| 429 | Per-key rate limit exceeded | Back off until the next rate-limit window. |
| 500 | Internal error | Show a fallback and do not blindly retry. |
| 503 | Runtime temporarily unavailable | Retry with bounded exponential backoff. |

AICC errors are flat, for example `{"error":"Too many requests","code":"E4403"}`. For SSE, a successfully settled turn ends with `done`; a runtime or settlement failure ends with an `error` event and no `done` event.

## LLM/Agent Context

Use the following files when asking ChatGPT, Claude, Codex, or another coding agent to integrate Prosody AICC:

- `/llms.txt`: documentation index.
- `/llms-full.txt`: all available documentation in one text file.
- `/docs-md/aicc`: this page as Markdown.

Prompt example:

```txt
Use the Prosody AICC documentation from /docs-md/aicc.
Implement a server-side proxy and a browser chat widget.
Do not expose PROSODY_API_KEY to the browser.
```

---
url: https://console.humelo.com/docs/web-widget
markdown: https://console.humelo.com/docs-md/web-widget
title: Web Widget
category: Agent
---

# Web Widget

Install the Prosody agent widget with one script tag. Browser code should use a public widget key only; private API keys must stay on your server.

## Install

```html
<script
  src="https://console.humelo.com/agent-widget.js"
  data-public-key="pk_widget_xxxxxxxxxxxxxxxx"
  async
></script>
```

## Events

```ts
window.ProsodyAgent?.on?.("conversation.opened", (event) => {
  console.log(event.sessionId);
});
window.ProsodyAgent?.on?.("agent.message", (event) => {
  console.log(event.content);
});
window.ProsodyAgent?.on?.("handoff.created", (event) => {
  console.log(event.conversationId);
});
window.ProsodyAgent?.on?.("conversation.closed", (event) => {
  console.log(event.reason);
});
```

The public widget does not currently emit tool-call events. Agent, theme, copy, features, and allowed domains are loaded from the server-side configuration associated with the public key.

---
url: https://console.humelo.com/docs/service-integrations
markdown: https://console.humelo.com/docs-md/service-integrations
title: Service Integrations
category: Agent
---

# Service Integrations

Service integrations connect an agent conversation to the tools your operation team already uses.

## Available now

- Slack Incoming Webhook is the only self-service integration currently available.
- It sends web-widget first-conversation and human-escalation notifications.
- The Console can save the Slack URL and send a test message.

## Enterprise inquiry

Discord, KakaoTalk Channel, Zendesk, MCP servers, and generic Webhooks are enterprise inquiry options. They are shown as planned integration scopes and cannot currently be configured or used as self-service features. Slack does not currently promise failed-conversation summaries or daily reports.

---
url: https://console.humelo.com/docs/dive
markdown: https://console.humelo.com/docs-md/dive
title: DIVE Standard API
category: Speech Synthesis
---

# DIVE Standard API

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

## 음성 합성

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

```http
POST https://api-console.humelo.net/api/v1/dive
```

### 인증 및 헤더

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

### 목소리 선택 방법

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

#### 프리셋 목소리 (기본)

- `mode`: `"preset"` (생략 가능)
- 함께 보낼 필드: `voiceName`, `emotion`
- Humelo가 제공하는 목소리 이름과 지원 감정을 선택합니다.

#### 저장된 목소리

- `mode`: `"saved"`
- 함께 보낼 필드: `savedVoiceId`
- 목소리 등록 API로 만든 저장 목소리 ID를 사용합니다.

#### 참조 토큰 직접 전달

- `mode`: `"saved"`
- 함께 보낼 필드: `referenceTokens`
- 저장 목소리 ID 대신 참조 토큰을 요청에 직접 넣습니다.

### 요청 필드

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `text` | string \| string[] | 필수 | - | 합성할 텍스트입니다. 배열이면 순서대로 이어서 처리합니다. 계정별 최대 길이 적용; 별도 설정이 없으면 500 UTF-16 code unit |
| `mode` | "preset" \| "saved" | 선택 | "preset" | 목소리 선택 방법입니다. preset은 voiceName과 emotion을, saved는 savedVoiceId 또는 referenceTokens를 사용합니다. |
| `lang` | string | 선택 | "ko" | 합성 언어 코드입니다. |
| `outputFormat` | string | 선택 | "wav_48000" | 오디오 포맷입니다. 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 |
| `rawData` | boolean | 선택 | false | true면 JSON 대신 선택한 포맷의 오디오 바이트를 직접 반환합니다. |
| `enableTimestamps` | boolean | 선택 | false | 권한이 있는 계정에서 타임스탬프 배열을 JSON 응답에 포함합니다. |
| `speed` | number | 선택 | 1 | 재생 속도입니다. 범위를 벗어나면 서버가 보정합니다. 0.5–2.0 |
| `pitch` | number | 선택 | 0 | 피치 조절값입니다. 범위를 벗어나면 서버가 보정합니다. -6–6 |
| `volume` | number | 선택 | 50 | 출력 볼륨입니다. 범위를 벗어나면 서버가 허용 범위로 보정합니다. 1–100 |
| `sentenceSilenceSec` | number | 선택 | 0.4 | Gateway가 텍스트를 여러 문장으로 나눈 뒤, 완성된 문장 오디오 사이에 직접 삽입하는 무음 길이(초)입니다. 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가 없으면 필수 |

### 요청 예시

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

### 응답

#### 200 · JSON 응답

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

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `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 대신 오디오 바이트를 반환합니다.

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

#### 4xx/5xx · 오류 응답

```json
{
  "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의 자동 대체·폐기 경로가 아닙니다.

---
url: https://console.humelo.com/docs/dive-streaming
markdown: https://console.humelo.com/docs-md/dive-streaming
title: DIVE Streaming API
category: Speech Synthesis
---

# DIVE Streaming API

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

## 스트리밍 음성 합성

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

```http
POST https://api-console.humelo.net/api/v1/dive/stream
```

### 인증 및 헤더

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

### 목소리 선택 방법

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

#### 프리셋 목소리 (기본)

- `mode`: `"preset"` (생략 가능)
- 함께 보낼 필드: `voiceName`, `emotion`
- Humelo가 제공하는 목소리 이름과 지원 감정을 선택합니다.

#### 저장된 목소리

- `mode`: `"saved"`
- 함께 보낼 필드: `savedVoiceId`
- 목소리 등록 API로 만든 저장 목소리 ID를 사용합니다.

#### 참조 토큰 직접 전달

- `mode`: `"saved"`
- 함께 보낼 필드: `referenceTokens`
- 저장 목소리 ID 대신 참조 토큰을 요청에 직접 넣습니다.

### 요청 필드

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `text` | string \| string[] | 필수 | - | 합성할 텍스트입니다. 배열이면 순서대로 이어서 처리합니다. 계정별 최대 길이 적용; 별도 설정이 없으면 500 UTF-16 code unit |
| `mode` | "preset" \| "saved" | 선택 | "preset" | 목소리 선택 방법입니다. preset은 voiceName과 emotion을, saved는 savedVoiceId 또는 referenceTokens를 사용합니다. |
| `lang` | string | 선택 | "ko" | 합성 언어 코드입니다. |
| `outputFormat` | string | 선택 | "mp3_48000_128" | 스트리밍 오디오 포맷입니다. 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 |
| `volume` | number | 선택 | 50 | 출력 볼륨입니다. 범위를 벗어나면 서버가 허용 범위로 보정합니다. 1–100 |
| `sentenceSilenceSec` | number | 선택 | 0.4 | Gateway가 전달한 문장 순번을 바탕으로 DIVE 엔진이 두 번째 이후 문장 스트림 앞에 삽입하는 무음 길이(초)입니다. 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가 없으면 필수 |

### 요청 예시

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

### 응답

#### 200 · 오디오 스트림

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

```http
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 오류 형식으로 반환됩니다.

```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로 정규화됩니다.

---
url: https://console.humelo.com/docs/dive-websocket
markdown: https://console.humelo.com/docs-md/dive-websocket
title: DIVE WebSocket API
category: Speech Synthesis
---

# DIVE WebSocket API

연결 하나를 유지하면서 여러 합성 요청의 이벤트와 오디오 바이너리 프레임을 순차적으로 받습니다.

## WebSocket 음성 합성

연결 후 15초 안에 첫 JSON text message를 보내세요. completed 이벤트를 받은 뒤 같은 연결에서 다음 요청을 보낼 수 있으며, 요청은 한 번에 하나씩 처리됩니다.

```http
GET wss://api-console.humelo.net/api/v1/dive/ws
```

### 인증 및 헤더

```http
X-API-Key: {YOUR_API_KEY}
# 또는
Authorization: Bearer {YOUR_API_KEY}
```

### 목소리 선택 방법

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

#### 프리셋 목소리 (기본)

- `mode`: `"preset"` (생략 가능)
- 함께 보낼 필드: `voiceName`, `emotion`
- Humelo가 제공하는 목소리 이름과 지원 감정을 선택합니다.

#### 저장된 목소리

- `mode`: `"saved"`
- 함께 보낼 필드: `savedVoiceId`
- 목소리 등록 API로 만든 저장 목소리 ID를 사용합니다.

#### 참조 토큰 직접 전달

- `mode`: `"saved"`
- 함께 보낼 필드: `referenceTokens`
- 저장 목소리 ID 대신 참조 토큰을 요청에 직접 넣습니다.

### 첫 text message 필드

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `text` | string \| string[] | 필수 | - | 합성할 텍스트입니다. 배열이면 순서대로 이어서 처리합니다. 계정별 최대 길이 적용; 별도 설정이 없으면 500 UTF-16 code unit |
| `mode` | "preset" \| "saved" | 선택 | "preset" | 목소리 선택 방법입니다. preset은 voiceName과 emotion을, saved는 savedVoiceId 또는 referenceTokens를 사용합니다. |
| `lang` | string | 선택 | "ko" | 합성 언어 코드입니다. |
| `outputFormat` | string | 선택 | "mp3_48000_128" | 스트리밍 오디오 포맷입니다. 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 |
| `volume` | number | 선택 | 50 | 출력 볼륨입니다. 범위를 벗어나면 서버가 허용 범위로 보정합니다. 1–100 |
| `sentenceSilenceSec` | number | 선택 | 0.4 | Gateway가 전달한 문장 순번을 바탕으로 DIVE 엔진이 두 번째 이후 문장 스트림 앞에 삽입하는 무음 길이(초)입니다. 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가 없으면 필수 |

### 요청 예시

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

### 응답

#### text · accepted 이벤트

인증, 검증, 사용량 예약이 완료되면 전송됩니다.

```json
{
  "type": "accepted",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "outputFormat": "mp3_48000_128",
  "contentType": "audio/mpeg"
}
```

#### binary · 오디오 메시지

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

#### text · completed 이벤트

```json
{
  "type": "completed",
  "jobId": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### text · error 이벤트

```json
{
  "type": "error",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "code": "E5002",
    "message": "Service temporarily unavailable",
    "details": "No DIVE engine capacity available"
  }
}
```

### 주의사항

- 브라우저 기본 WebSocket API는 handshake header를 지정할 수 없으므로 서버 SDK에서 연결하세요.
- API Key를 URL query parameter에 넣는 방식은 지원하지 않습니다.
- 각 completed 이벤트를 받은 뒤 다음 JSON text 요청을 보내면 같은 연결을 재사용할 수 있습니다.
- accepted 전을 포함해 이전 요청이 처리 중일 때 다음 요청을 보내면 E4201 error와 1008 정책 위반으로 연결이 종료됩니다.
- completed 이후 합성 요청이나 표준 WebSocket ping이 5분 동안 없으면 서버가 1000으로 연결을 정상 종료합니다.
- 유휴 연결을 유지하려면 고객 서버에서 30초 간격의 표준 WebSocket ping control frame을 권장합니다. ping은 idle timeout을 다시 시작하지만 job, rate limit, 사용량을 만들지 않습니다.
- 같은 연결을 재사용해도 각 합성 요청은 별도로 인증·rate limit·사용량 정산됩니다.
- 각 JSON text 요청은 최대 10 MiB이며, 잘못되거나 찾을 수 없는 dictionaryId는 E4301 error 이벤트 후 연결 종료로 처리됩니다.
- 단어장 DB/RPC 조회 장애는 E5002 error 이벤트 후 연결 종료로 처리됩니다.

## WebSocket close code

표준 WebSocket close code를 사용합니다. completed 후에는 기존 연결을 재사용할 수 있고, 표준 ping으로 요청 사이 idle timeout을 연장할 수 있습니다. 오류로 닫힌 경우 새 연결에서 재시도하세요.

| 코드 | 조건 | 권장 처리 |
| --- | --- | --- |
| 1000 | 합성 요청·WebSocket ping 없이 5분 idle 또는 정상 종료 | 필요하면 새 연결 |
| 1003 | 첫 메시지가 JSON text가 아님 | 요청 형식 수정 |
| 1008 | 잘못된 요청, 권한, 겹치는 요청, 초기 요청 시간 초과 | 요청 수정 후 새 연결 |
| 1011 | 합성 중 서버 내부 오류 | 제한적으로 재시도 |
| 1012 | Gateway 재시작 또는 drain | backoff 후 새 연결 |
| 1013 | 사용량·rate limit 또는 일시적 서비스 불가 | 제한 확인 후 backoff |

---
url: https://console.humelo.com/docs/saved-voices
markdown: https://console.humelo.com/docs-md/saved-voices
title: Saved Voices
category: Speech Synthesis
---

# Saved Voices API

Pre-approved organizations can register Korean and English voice samples and reuse them in DIVE saved mode.

## Register voice

Send audio and an exact transcript for at least one language as multipart/form-data. Organizations without saved-voice approval receive E4101/403.

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

### Authentication and headers

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

### Request fields

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Required | - | Name to save for the voice. Up to 50 characters |
| `description` | string | Optional | - | Voice description. Up to 200 characters |
| `audioFileKo` | File | Conditional | - | Korean audio file. Required when audioFileEn is absent |
| `audioTextKo` | string | Conditional | - | Exact transcript of the Korean audio file. Paired with audioFileKo; must contain Korean |
| `audioFileEn` | File | Conditional | - | English audio file. Required when audioFileKo is absent |
| `audioTextEn` | string | Conditional | - | Exact transcript of the English audio file. Paired with audioFileEn; must not contain Korean |

### Request example

```bash
curl -X POST "https://agitvxptajouhvoatxio.supabase.co/functions/v1/register-dive-voice-v1" \
  -H "X-API-Key: {YOUR_API_KEY}" \
  -F "name=Customer support voice" \
  -F "audioFileKo=@voice-ko.wav" \
  -F "audioTextKo=Hello. This is the customer support voice."
```

### Response

#### 201 · Registration result

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | UUID | Required | - | ID of the created voice. |
| `name` | string | Required | - | Saved name. |
| `status` | "completed" | Required | - | For a bilingual request, reference-token generation succeeded for at least one language. It does not mean both languages succeeded. |

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Customer support voice",
  "status": "completed"
}
```

#### 400 · E4201 / E4203 · Input or audio error

A multipart field is missing, a language transcript is invalid, or a decoded file is outside the 2–20 second range.

#### 403 · E4101 · Pre-approval required

The organization does not have access to saved voices.

#### 503 · E5002 · Reference-file Storage temporarily unavailable

A requested reference-file upload failed. The API does not return completed and compensates the created row and Storage prefix. If Storage cleanup also fails, a traceable failed row is retained.

### Notes

- Accepted extensions are wav, mp3, m4a, webm, ogg, and flac; each audio file must be 2–20 seconds long.
- The multipart request and the combined uploaded audio are each limited to 50 MiB.
- Database rows and Storage objects are created only after every uploaded file passes duration validation. Validation failures leave no partial row or file.
- For a bilingual request, status is currently completed even when token generation succeeds for only one language. The response has no per-language failure reason; the list exposes only englishAvailable, with no separate Korean-availability field.
- A Korean-only registration attempts English generation in the background, so englishAvailable may be false immediately after completed. Background failures are not added to the registration response.
- Legacy audioFile/audioText fields remain supported, but new integrations should use the per-language fields.

## List voices

Lists the organization's saved voices in newest-first order.

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

### Authentication and headers

```http
X-API-Key: {YOUR_API_KEY}
```

### Response

#### 200 · List response

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `voices` | object[] | Required | - | List of id, name, description, englishAvailable, usageCount, status, and createdAt values. |

```json
{
  "voices": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Customer support voice",
      "description": null,
      "englishAvailable": false,
      "usageCount": 0,
      "status": "completed",
      "createdAt": "2026-07-28T00:00:00.000Z"
    }
  ]
}
```

## Delete voice

Deletes an organization-owned voice and its stored reference files.

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

### Authentication and headers

```http
X-API-Key: {YOUR_API_KEY}
```

### Path parameters

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | UUID | Required | - | Saved voice ID to delete. |

### Response

#### 200 · Deleted

The response body is empty.

#### 500 · E5001 · Storage or database cleanup failed

Storage listing or deletion, or database deletion, failed. The database row is retained when Storage cleanup fails.

### Notes

- Storage objects are listed and deleted in batches of 1,000, and the database row is deleted only after every result is verified. Storage cleanup failure returns E5001 and retains the row.

---
url: https://console.humelo.com/docs/frtts
markdown: https://console.humelo.com/docs-md/frtts
title: FRTTS API
category: Speech Synthesis
---

# FRTTS API

짧은 텍스트를 프리셋 음성으로 합성하고 완성된 WAV URL을 반환합니다.

## 음성 합성

voiceId 또는 voiceName 중 하나로 목소리를 선택합니다.

```http
POST https://agitvxptajouhvoatxio.supabase.co/functions/v1/tts-synthesize-v1
```

### 인증 및 헤더

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

### 요청 필드

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `text` | string | 필수 | - | 합성할 텍스트입니다. 최대 240자 |
| `voiceId` | UUID | 조건부 | - | 정확한 음성·감정 변형을 가리키는 목소리 ID입니다. voiceName이 없으면 필수 |
| `voiceName` | string | 조건부 | - | 프리셋 목소리 이름입니다. voiceId가 없으면 필수 |
| `emotion` | string | 선택 | "neutral" | voiceName으로 선택할 감정입니다. voiceId를 사용하면 ID에 포함된 감정이 적용됩니다. |
| `dictionaryId` | UUID | 선택 | - | 합성 전에 적용할 조직 소유 단어장 ID입니다. |
| `settings` | object | 선택 | - | 속도, 피치, 볼륨 설정 객체입니다. |
| `settings.speed` | number | 선택 | 1.0 | 재생 속도 배율입니다. |
| `settings.pitch` | number | 선택 | 0 | 피치 조절값입니다. 서버가 -10–10 범위로 보정합니다. -10–10 |
| `settings.volume` | number | 선택 | 1.0 | 볼륨 비율입니다. 1.0이 기본 출력 볼륨입니다. 권장 0–1 |

### 요청 예시

```json
{
  "text": "안녕하세요. FRTTS 음성 합성 테스트입니다.",
  "voiceName": "시아",
  "emotion": "neutral",
  "settings": {
    "speed": 1,
    "pitch": 0,
    "volume": 1
  }
}
```

### 응답

#### 200 · 합성 결과

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `jobId` | UUID | 필수 | - | 생성된 TTS 작업 ID입니다. |
| `audioUrl` | string | 필수 | - | 완성된 WAV 오디오 URL입니다. |

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

#### 400 · E4201 / E4202 · 입력 오류

text, voiceId, voiceName, emotion, dictionaryId, settings 또는 하위 설정 값의 타입이 잘못되었거나 텍스트가 너무 긴 경우입니다.

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

#### 402 · E4601 · 크레딧 부족

FRTTS 작업을 예약할 크레딧이 부족합니다.

#### 404 · E4301 · 단어장 없음

dictionaryId가 조직에서 찾을 수 없는 단어장을 가리킵니다.

#### 503 · E5002 · 단어장 조회 일시 불가

단어장 DB/RPC 조회를 일시적으로 사용할 수 없습니다.

### 주의사항

- JSON 요청 body는 최대 1 MiB입니다.

---
url: https://console.humelo.com/docs/stt
markdown: https://console.humelo.com/docs-md/stt
title: STT API
category: Speech Recognition
---

# STT API

오디오 URL 또는 Base64 데이터를 텍스트와 단어별 타임스탬프로 변환합니다.

## 음성 인식

audioUrl과 audioData 중 하나를 전달합니다.

```http
POST https://agitvxptajouhvoatxio.supabase.co/functions/v1/stt-transcribe-v1
```

### 인증 및 헤더

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

### 요청 필드

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `audioUrl` | string (URL) | 조건부 | - | 서버가 내려받을 오디오 URL입니다. audioData가 없으면 필수 |
| `audioData` | string (Base64) | 조건부 | - | Base64 오디오 또는 `data:audio/...;base64,...` 형식입니다. audioUrl이 없으면 필수 |
| `lang` | string | 선택 | "ko" | 인식 언어 코드입니다. |

### 요청 예시

```json
{
  "audioUrl": "https://example.com/audio.mp3",
  "lang": "ko"
}
```

### 응답

#### 200 · 인식 결과

| 필드 | 타입 | 필수 여부 | 기본값 | 설명 |
| --- | --- | --- | --- | --- |
| `jobId` | UUID | 필수 | - | 생성된 STT 작업 ID입니다. |
| `transcript` | string | 필수 | - | 전체 인식 텍스트입니다. |
| `confidence` | number | 필수 | - | 전체 인식 신뢰도입니다. |
| `words` | object[] | 선택 | - | 단어별 startTime, endTime, confidence입니다. |
| `processingTimeMs` | number | 필수 | - | 서버 처리 시간(ms)입니다. |

```json
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "transcript": "안녕하세요.",
  "confidence": 0.98,
  "words": [
    { "word": "안녕하세요", "startTime": 0, "endTime": 0.82, "confidence": 0.99 }
  ],
  "processingTimeMs": 842
}
```

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

audioUrl, audioData, lang 타입이 잘못되었거나 오디오 형식·길이를 검증할 수 없는 경우입니다.

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

#### 402 · E4601 · 크레딧 부족

STT 작업을 예약할 크레딧이 부족합니다.

### 주의사항

- 지원 형식은 WAV, MP3, M4A, AAC, WebM, MP4이며 최대 파일 크기는 50 MiB입니다.
- 인증된 요청의 최대 길이는 3,600초이고 게스트 요청은 30초입니다.
- audioUrl은 서버가 15초 제한으로 내려받으며 리디렉션과 사설 네트워크 주소를 제한합니다.

---
url: https://console.humelo.com/docs/dictionaries
markdown: https://console.humelo.com/docs-md/dictionaries
title: Dictionaries
category: Utilities
---

# Dictionaries API

Create organization-scoped replacement rules and apply them to DIVE or FRTTS synthesis requests.

## Create dictionary

Creates a dictionary with an empty entries object.

```http
POST https://agitvxptajouhvoatxio.supabase.co/functions/v1/dictionaries-v1
```

### Authentication and headers

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

### Request fields

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Required | - | Dictionary name. 1–100 characters |
| `description` | string | Optional | - | Description. Up to 500 characters |
| `caseSensitive` | boolean | Optional | true | Whether English replacements are case-sensitive. |

### Request example

```json
{
  "name": "Product pronunciations",
  "description": "Brand and product replacement rules",
  "caseSensitive": true
}
```

### Response

#### 201 · Created

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | UUID | Required | - | ID of the created dictionary. |

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### 400 · E4201 · Invalid JSON or field type

The body is not a JSON object, or name, description, or caseSensitive has the wrong type.

#### 503 · E5002 · Dictionary DB/RPC temporarily unavailable

The plan check, dictionary count lookup, or dictionary storage DB/RPC is temporarily unavailable.

## List dictionaries

Lists the organization's active dictionaries in creation order.

```http
GET https://agitvxptajouhvoatxio.supabase.co/functions/v1/dictionaries-v1
```

### Authentication and headers

```http
X-API-Key: {YOUR_API_KEY}
```

### Response

#### 200 · List response

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `dictionaries` | object[] | Required | - | List of id, name, description, and caseSensitive values. |

```json
{
  "dictionaries": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Product pronunciations",
      "description": "Brand and product replacement rules",
      "caseSensitive": true
    }
  ]
}
```

#### 503 · E5002 · Dictionary DB temporarily unavailable

The dictionary list database is temporarily unavailable.

## Get dictionary

Gets one dictionary, including its entries.

```http
GET https://agitvxptajouhvoatxio.supabase.co/functions/v1/dictionaries-v1/{id}
```

### Authentication and headers

```http
X-API-Key: {YOUR_API_KEY}
```

### Path parameters

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | UUID | Required | - | Dictionary ID to retrieve. |

### Response

#### 200 · Dictionary response

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | UUID | Required | - | Dictionary ID. |
| `name` | string | Required | - | Dictionary name. |
| `description` | string \| null | Optional | - | Description. |
| `entries` | Record<string, string> | Required | - | Source and replacement text pairs. |
| `caseSensitive` | boolean | Required | - | Whether matching is case-sensitive. |
| `createdAt` | ISO 8601 | Required | - | Creation timestamp. |
| `updatedAt` | ISO 8601 | Required | - | Last-updated timestamp. |

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Product pronunciations",
  "description": null,
  "entries": { "API": "A P I" },
  "caseSensitive": true,
  "createdAt": "2026-07-28T00:00:00.000Z",
  "updatedAt": "2026-07-28T00:00:00.000Z"
}
```

#### 404 · E4301 · Dictionary not found or inaccessible

The dictionary does not exist in this organization or belongs to another organization.

#### 503 · E5002 · Dictionary DB/RPC temporarily unavailable

The dictionary lookup DB/RPC is temporarily unavailable.

## Update dictionary

Updates only the supplied fields; at least one field is required.

```http
PATCH https://agitvxptajouhvoatxio.supabase.co/functions/v1/dictionaries-v1/{id}
```

### Authentication and headers

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

### Path parameters

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | UUID | Required | - | Dictionary ID to update. |

### Request fields

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | Optional | - | New name. 1–100 characters |
| `description` | string | Optional | - | New description. Up to 500 characters |
| `caseSensitive` | boolean | Optional | - | New case-sensitivity setting. |
| `entries` | Record<string, string> | Optional | - | Complete replacement-rules object. Each key and value is at most 100 characters; entry count is plan-limited |

### Request example

```json
{
  "entries": {
    "API": "A P I",
    "Humelo": "Humelo"
  }
}
```

### Response

#### 200 · Updated

The response body is empty.

#### 400 · E4201 · Invalid JSON or field type

The body is not a JSON object, or name, description, caseSensitive, or entries has the wrong type. Whitespace-only names and entry keys or values are rejected, and the string "false" is not coerced to boolean false. Rejected requests do not modify the database row.

#### 404 · E4301 · Dictionary not found or inaccessible

The dictionary does not exist in this organization or belongs to another organization.

#### 503 · E5002 · Dictionary DB/RPC temporarily unavailable

The ownership check, plan-limit check, or dictionary storage DB/RPC is temporarily unavailable.

## Delete dictionary

Deletes a dictionary owned by the organization.

```http
DELETE https://agitvxptajouhvoatxio.supabase.co/functions/v1/dictionaries-v1/{id}
```

### Authentication and headers

```http
X-API-Key: {YOUR_API_KEY}
```

### Path parameters

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | UUID | Required | - | Dictionary ID to delete. |

### Response

#### 200 · Deleted

The response body is empty.

#### 404 · E4301 · Dictionary not found or inaccessible

The dictionary does not exist in this organization or belongs to another organization.

#### 503 · E5002 · Dictionary DB temporarily unavailable

The ownership check or dictionary deletion database is temporarily unavailable.

---
url: https://console.humelo.com/docs/error-codes
markdown: https://console.humelo.com/docs-md/error-codes
title: Error Codes
category: Reference
---

# Error Codes

Prosody voice APIs return a nested error object. AICC keeps a flat response for compatibility, but uses the same common code values.

## Voice API format

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

## AICC format

```json
{
  "error": "message or a user message in history is required",
  "code": "E4201"
}
```

## Reference

| Code | HTTP | Name | Meaning |
| --- | ---: | --- | --- |
| `E4001` | 401 | `API_KEY_MISSING` | API key is missing. |
| `E4002` | 401 | `API_KEY_INVALID` | API key is invalid. |
| `E4101` | 403 | `PERMISSION_DENIED` | The caller does not have access to the feature or resource. |
| `E4201` | 400 | `INVALID_REQUEST` | The request body or field value is invalid. |
| `E4202` | 400 | `TEXT_TOO_LONG` | Text exceeds the allowed length. |
| `E4203` | 400 | `INVALID_AUDIO` | Audio format, size, or duration is invalid. |
| `E4204` | 413 | `PAYLOAD_TOO_LARGE` | The request body exceeds the endpoint limit. |
| `E4301` | 404 | `RESOURCE_NOT_FOUND` | The requested voice, dictionary, agent, or other resource was not found. |
| `E4302` | 409 | `RESOURCE_NOT_READY` | The resource exists but is not ready for this request. |
| `E4401` | 429 | `USAGE_LIMIT_EXCEEDED` | The account usage limit was exceeded. |
| `E4402` | 429 | `GUEST_LIMIT_EXCEEDED` | The guest daily limit was exceeded. |
| `E4403` | 429 | `RATE_LIMIT_EXCEEDED` | The per-minute request or character limit was exceeded. |
| `E4501` | 405 | `METHOD_NOT_ALLOWED` | The HTTP method is not supported. |
| `E4601` | 402 | `INSUFFICIENT_CREDITS` | The organization does not have enough credits to reserve the request. |
| `E5001` | 500 | `INTERNAL_ERROR` | An internal server error occurred. |
| `E5002` | 503 | `SERVICE_UNAVAILABLE` | The service is temporarily unavailable. |
| `E5003` | 500 | `PROCESSING_TIMEOUT` | Processing exceeded the endpoint timeout. |

Retry only `E5002` and transient transport failures with backoff. Fix the request or account state before retrying other 4xx errors.