서비스 소개

발음평가 (단문)

문장·단어 단위 인식입니다. 긴 문단은 발음평가 (장문)을 사용하세요.

REST 프로토콜

요청 필드 JSON 기준

호출 샘플

curl -X POST "https://{host}/api/v1/sr/recognize" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'request={"user_sid":"user-2001","params":{"text":"Hello world","resource_name":"KONG_ALL",
       "audio_format":{"sample_rate":16000,"channels":1,"encoding":"pcm"}}};type=application/json' \
  -F "audio=@hello.wav"

import requests, json

resp = requests.post(
    "https://{host}/api/v1/sr/recognize",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files={
        "request": (None, json.dumps({
            "user_sid": "user-2001",
            "params": {"text": "Hello world", "resource_name": "KONG_ALL"},
        }), "application/json"),
        "audio": ("hello.wav", open("hello.wav", "rb"), "audio/wav"),
    },
)
body = resp.json()
print(body)

const fs = require("fs");
const path = require("path");

const HOST = "https://{host}";

async function main() {
    const filePath = "./hello.wav";

    const fd = new FormData();

    fd.append(
        "request",
        new Blob(
            [
                JSON.stringify({
                    user_sid: "user-2001",
                    params: {
                        text: "Hello world",
                        resource_name: "KONG_ALL",
                    },
                }),
            ],
            { type: "application/json" }
        )
    );

    const file = new Blob([fs.readFileSync(filePath)]);
    fd.append("audio", file, path.basename(filePath));

    const res = await fetch(`${HOST}/api/v1/sr/recognize`, {
        method: "POST",
        headers: {
            Authorization: `Bearer ${API_KEY}`,
        },
        body: fd,
    });

    if (!res.ok) {
        console.error("HTTP Error:", res.status, await res.text());
        return;
    }

    const json = await res.json();
    console.log(json);
}

main();

응답 예시 (200)

{
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "result": {
    "result_type": "recognition",
    "text": "Hello world",
    "score": 95,
    "words": [
      { "text": "Hello", "score": 97, "start_ms": 0,   "end_ms": 500,
        "raw_data": { "phonemes": [
          { "str": "HH", "score": 95, "is_vowel": false, "start_ms": 0,   "end_ms": 80  },
          { "str": "AH", "score": 98, "is_vowel": true,  "start_ms": 80,  "end_ms": 300 },
          { "str": "L",  "score": 96, "is_vowel": false, "start_ms": 300, "end_ms": 500 }
        ]}},
      { "text": "world", "score": 93, "start_ms": 520, "end_ms": 990,
        "raw_data": { "phonemes": [
          { "str": "W",  "score": 90, "is_vowel": false, "start_ms": 520, "end_ms": 620 },
          { "str": "ER", "score": 95, "is_vowel": true,  "start_ms": 620, "end_ms": 990 }
        ]}}
    ]
  },
  "statistics": { "audio_duration": 1.5, "processing_time": 0.3 },
  "server_time": "2026-02-12T10:30:45Z"
}

응답 REST 응답 본문 — 필드는 결과 구조체를 참고하세요

WebSocket 프로토콜

한 연결에서 아래 순서로 메시지를 주고받습니다. Text 프레임은 JSON 제어 메시지이고, Binary 프레임은 오디오입니다. 아래 요청·응답 필드는 모두 JSON 메시지 기준입니다. 연결 인증은 인증 (API Key)과 브라우저 인증을 참고하세요.

SR · 발음평가 (단문) 세션 흐름도

     Client                              Server
     ──────                              ──────
 ①  session.start           ─▶
                            ◀─  session.started       (session_id 발급)
 ②  command: start_audio    ─▶
                            ◀─  command.ack
 ③  [binary audio frame]    ─▶
                            ◀─  data_chunk.ack        (프레임마다 1회)
 ④  command: finalize_audio ─▶
                            ◀─  command.ack
                            ◀─  recognition.result    (최종 결과)
 ⑤  session.end             ─▶
                            ◀─  session.ended

 ※  session.heartbeat       ─▶   (① ~ ⑤ 사이, 30초 권장)
                            ◀─  session.heartbeat.ack

① session.start — 세션 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.started

// 클라이언트 → 서버
{
  "type": "session.start",
  "user_sid": "user-2001",
  "service": "sr",
  "operation": "recognize",
  "params": {
    "text": "Hello world",
    "resource_name": "KONG_ALL",
    "audio_format": { "sample_rate": 16000, "channels": 1, "encoding": "pcm" }
  }
}

// 서버 → 클라이언트
{
  "type": "session.started",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "subscription_uuid": "…",
  "subscription_plan_uid": 0,
  "subscription_status": "…",
  "server_time": "2026-02-12T10:30:45Z"
}

② command: start_audio — 오디오 수신 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · command.ack

// 클라이언트 → 서버
{ "type": "command", "command": "start_audio" }

// 서버 → 클라이언트
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "start_audio",
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 85000
}

③ Binary 오디오 프레임 — 오디오 전송

요청 Client → Server · Binary 프레임

응답 Server → Client · data_chunk.ack (프레임마다 1회)

// 서버 → 클라이언트
{
  "type": "data_chunk.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "bytes": 48044,
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 412000
}

④ command: finalize_audio — 수신 종료 · 인식 실행

요청 Client → Server · Text 프레임 (JSON)

응답 1 Server → Client · command.ack

응답 2 Server → Client · recognition.result — 필드는 결과 구조체를 참고하세요

// 클라이언트 → 서버
{ "type": "command", "command": "finalize_audio" }

// 서버 → 클라이언트 (1) 커맨드 수락
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "server_time": "2026-02-12T10:30:46Z",
  "server_processing_time_ns": 310000000
}

// 서버 → 클라이언트 (2) 인식 결과
{
  "type": "recognition.result",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "is_final": true,
  "result": {
    "result_type": "recognition",
    "text": "Hello world",
    "score": 95,
    "words": [ … ]
  },
  "statistics": { … },
  "server_time": "2026-02-12T10:30:46Z"
}

⑤ session.end — 세션 종료

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.ended

// 클라이언트 → 서버
{ "type": "session.end", "reason": "completed" }

// 서버 → 클라이언트
{
  "type": "session.ended",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "reason": "completed",
  "statistics": { "frames_received": 1, "audio_bytes": 48044 },
  "server_time": "2026-02-12T10:30:47Z"
}

오류 응답

서버는 상황에 따라 두 종류의 오류 메시지를 보냅니다. 오류 코드는 에러 코드를 참고하세요.

{
  "type": "command.error",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "error": { "code": "INVALID_MESSAGE", "message": "…", "ap_request_id": "…" },
  "server_time": "2026-02-12T10:30:46Z"
}

결과 구조체 REST · WebSocket 공용 · JSON 기준

아래 표는 REST 응답 본문과 WebSocket recognition.result 메시지에 공통으로 적용됩니다. REST는 응답 본문 최상위에, WebSocket은 결과 메시지 본문에 같은 필드가 담기며, WebSocket 메시지에는 type·is_final이 추가됩니다. REST 전용 표시가 있는 필드는 WebSocket 결과 메시지에 없습니다.

발음평가 (장문)

문단 단위 인식입니다. 문장·단어 단위는 발음평가 (단문)을 사용하세요.

REST 프로토콜

요청 필드 JSON 기준

호출 샘플

curl -X POST "https://{host}/api/v1/sr/recognize_long" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'request={"user_sid":"user-2001","params":{"text":"This is my family. My father is a doctor. My mother is a teacher.",
       "resource_name":"KONG_ALL"}};type=application/json' \
  -F "audio=@paragraph.wav"

import requests, json

resp = requests.post(
    "https://{host}/api/v1/sr/recognize_long",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files={
        "request": (None, json.dumps({
            "user_sid": "user-2001",
            "params": {
                "text": "This is my family. My father is a doctor. My mother is a teacher.",
                "resource_name": "KONG_ALL",
            },
        }), "application/json"),
        "audio": ("paragraph.wav", open("paragraph.wav", "rb"), "audio/wav"),
    },
)
result = resp.json()["result"]
print(result["text"], result["score"])
# 미발화 어절은 score·start_ms·end_ms 가 0 으로 내려옵니다.
for w in result["words"]:
    print(w["text"], w["score"], w["raw_data"]["is_spoken"])

const fs = require("fs");
const path = require("path");

const HOST = "https://{host}";

async function main() {
    const filePath = "./paragraph.wav";

    const fd = new FormData();

    fd.append(
        "request",
        new Blob(
            [
                JSON.stringify({
                    user_sid: "user-2001",
                    params: {
                        text: "This is my family. My father is a doctor. My mother is a teacher.",
                        resource_name: "KONG_ALL",
                    },
                }),
            ],
            { type: "application/json" }
        )
    );

    fd.append("audio", new Blob([fs.readFileSync(filePath)]), path.basename(filePath));

    const res = await fetch(`${HOST}/api/v1/sr/recognize_long`, {
        method: "POST",
        headers: { Authorization: `Bearer ${API_KEY}` },
        body: fd,
    });

    if (!res.ok) {
        console.error("HTTP Error:", res.status, await res.text());
        return;
    }

    const result = (await res.json()).result;
    console.log(result.text, result.score);
}

main();

응답 REST 응답 본문 — 필드는 결과 구조체를 참고하세요

WebSocket 프로토콜

한 연결에서 아래 순서로 메시지를 주고받습니다. Text 프레임은 JSON 제어 메시지이고, Binary 프레임은 오디오입니다. 아래 요청·응답 필드는 모두 JSON 메시지 기준입니다. 연결 인증은 인증 (API Key)과 브라우저 인증을 참고하세요.

SR · 발음평가 (장문) 세션 흐름도

     Client                              Server
     ──────                              ──────
 ①  session.start           ─▶
                            ◀─  session.started       (session_id 발급)
 ②  command: start_audio    ─▶
                            ◀─  command.ack
 ③  [binary audio frame]    ─▶
                            ◀─  data_chunk.ack        (프레임마다 1회)
 ④  command: finalize_audio ─▶
                            ◀─  command.ack
                            ◀─  recognition.result    (최종 결과)
 ⑤  session.end             ─▶
                            ◀─  session.ended

 ※  session.heartbeat       ─▶   (① ~ ⑤ 사이, 30초 권장)
                            ◀─  session.heartbeat.ack

① session.start — 세션 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.started

// 클라이언트 → 서버
{
  "type": "session.start",
  "user_sid": "user-2001",
  "service": "sr",
  "operation": "recognize_long",
  "params": {
    "text": "Once upon a time there lived a little girl. She loved to read books.",
    "resource_name": "KONG_ALL",
    "audio_format": { "sample_rate": 16000, "channels": 1, "encoding": "pcm" }
  }
}

// 서버 → 클라이언트
{
  "type": "session.started",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "subscription_uuid": "…",
  "subscription_plan_uid": 0,
  "subscription_status": "…",
  "server_time": "2026-02-12T10:30:45Z"
}

② command: start_audio — 오디오 수신 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · command.ack

// 클라이언트 → 서버
{ "type": "command", "command": "start_audio" }

// 서버 → 클라이언트
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "start_audio",
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 85000
}

③ Binary 오디오 프레임 — 오디오 전송

요청 Client → Server · Binary 프레임

응답 Server → Client · data_chunk.ack (프레임마다 1회)

// 서버 → 클라이언트
{
  "type": "data_chunk.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "bytes": 16000,
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 412000
}

④ command: finalize_audio — 수신 종료 · 인식 실행

요청 Client → Server · Text 프레임 (JSON)

응답 1 Server → Client · command.ack

응답 2 Server → Client · recognition.result — 필드는 결과 구조체를 참고하세요

// 클라이언트 → 서버
{ "type": "command", "command": "finalize_audio" }

// 서버 → 클라이언트 (1) 커맨드 수락
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "server_time": "2026-02-12T10:30:46Z",
  "server_processing_time_ns": 310000000
}

// 서버 → 클라이언트 (2) 결과
{
  "type": "recognition.result",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "is_final": true,
  "result": {
    "result_type": "recognition",
    "text": "Once upon a time there lived a little girl. She loved to read books.",
    "score": 88,
    "words": [ … ]
  },
  "statistics": { … },
  "server_time": "2026-02-12T10:30:46Z"
}

⑤ session.end — 세션 종료

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.ended

// 클라이언트 → 서버
{ "type": "session.end", "reason": "completed" }

// 서버 → 클라이언트
{
  "type": "session.ended",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "reason": "completed",
  "statistics": { "frames_received": 1, "audio_bytes": 640044 },
  "server_time": "2026-02-12T10:30:47Z"
}

오류 응답

서버는 상황에 따라 두 종류의 오류 메시지를 보냅니다. 오류 코드는 에러 코드를 참고하세요.

{
  "type": "command.error",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "error": { "code": "INVALID_MESSAGE", "message": "…", "ap_request_id": "…" },
  "server_time": "2026-02-12T10:30:46Z"
}

결과 구조체 REST · WebSocket 공용 · JSON 기준

아래 표는 REST 응답 본문과 WebSocket recognition.result 메시지에 공통으로 적용됩니다. REST는 응답 본문 최상위에, WebSocket은 결과 메시지 본문에 같은 필드가 담기며, WebSocket 메시지에는 type·is_final이 추가됩니다. REST 전용 표시가 있는 필드는 WebSocket 결과 메시지에 없습니다.

비교평가

REST 프로토콜

요청 필드 JSON 기준

참조 지정 방식 2가지 중 하나를 사용합니다.

호출 샘플 — ① 참조 음성 직접 전달

curl -X POST "https://{host}/api/v1/sr/assess" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'request={"user_sid":"user-2001","params":{"reference_text":"Hello world",
       "resource_name":"KONG_ALL"}};type=application/json' \
  -F "reference_audio=@native.wav" \
  -F "audio=@student.wav"

import requests, json

resp = requests.post(
    "https://{host}/api/v1/sr/assess",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files={
        "request": (None, json.dumps({
            "user_sid": "user-2001",
            "params": {
                "reference_text": "Hello world",
                "resource_name": "KONG_ALL",
            },
        }), "application/json"),
        # 참조 음성과 사용자 음성을 각각 별도 파트로 전송
        "reference_audio": ("native.wav", open("native.wav", "rb"), "audio/wav"),
        "audio": ("student.wav", open("student.wav", "rb"), "audio/wav"),
    },
)
ass = resp.json()["result"]["ass_res"]
print(ass["overall"], ass["prosody_score"], ass["pronunciation_score"])

# ass_res.words[]는 점수만 제공하므로 어절 텍스트는 user_result에서 가져옵니다.
words = resp.json()["result"]["user_result"]["results"][0]["words"]
for w, sc in zip(words, ass["words"]):
    print(w["str"], sc["pronunciation"], sc["intonation"], sc["timing"], sc["loudness"])

const fs = require("fs");
const path = require("path");

const HOST = "https://{host}";

async function main() {
    const userPath = "./student.wav";
    const refPath  = "./native.wav";

    const fd = new FormData();

    fd.append(
        "request",
        new Blob(
            [
                JSON.stringify({
                    user_sid: "user-2001",
                    params: {
                        reference_text: "Hello world",
                        resource_name: "KONG_ALL",
                    },
                }),
            ],
            { type: "application/json" }
        )
    );

    // 참조 음성과 사용자 음성을 각각 별도 파트로 전송
    fd.append("reference_audio", new Blob([fs.readFileSync(refPath)]), path.basename(refPath));
    fd.append("audio", new Blob([fs.readFileSync(userPath)]), path.basename(userPath));

    const res = await fetch(`${HOST}/api/v1/sr/assess`, {
        method: "POST",
        headers: { Authorization: `Bearer ${API_KEY}` },
        body: fd,
    });

    if (!res.ok) {
        console.error("HTTP Error:", res.status, await res.text());
        return;
    }

    const ass = (await res.json()).result.ass_res;
    console.log(ass.overall, ass.prosody_score, ass.pronunciation_score);
}

main();

호출 샘플 — ② 서버에 등록된 참조 사용

# 참조 음성은 이미 서버에 등록되어 있으므로 reference_audio 파트를 보내지 않습니다.
curl -X POST "https://{host}/api/v1/sr/assess" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'request={"user_sid":"user-2001","params":{"reference_id":"ref-001",
       "resource_name":"KONG_ALL"}};type=application/json' \
  -F "audio=@student.wav"

import requests, json

# reference_id 대신 reference_resource_name · resource_key · resource_id 중
# 하나를 보내도 됩니다 (reference_id 가 가장 우선 적용).
resp = requests.post(
    "https://{host}/api/v1/sr/assess",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files={
        "request": (None, json.dumps({
            "user_sid": "user-2001",
            "params": {
                "reference_id": "ref-001",
                "resource_name": "KONG_ALL",
            },
        }), "application/json"),
        # 사용자 음성만 전송
        "audio": ("student.wav", open("student.wav", "rb"), "audio/wav"),
    },
)
ass = resp.json()["result"]["ass_res"]
print(ass["overall"], ass["prosody_score"], ass["pronunciation_score"])

const fs = require("fs");
const path = require("path");

const HOST = "https://{host}";

async function main() {
    const userPath = "./student.wav";

    const fd = new FormData();

    // reference_id 대신 reference_resource_name · resource_key · resource_id 중
    // 하나를 보내도 됩니다 (reference_id 가 가장 우선 적용).
    fd.append(
        "request",
        new Blob(
            [
                JSON.stringify({
                    user_sid: "user-2001",
                    params: {
                        reference_id: "ref-001",
                        resource_name: "KONG_ALL",
                    },
                }),
            ],
            { type: "application/json" }
        )
    );

    // 참조 음성은 서버에 등록되어 있어 사용자 음성만 전송합니다.
    fd.append("audio", new Blob([fs.readFileSync(userPath)]), path.basename(userPath));

    const res = await fetch(`${HOST}/api/v1/sr/assess`, {
        method: "POST",
        headers: { Authorization: `Bearer ${API_KEY}` },
        body: fd,
    });

    if (!res.ok) {
        console.error("HTTP Error:", res.status, await res.text());
        return;
    }

    const ass = (await res.json()).result.ass_res;
    console.log(ass.overall, ass.prosody_score, ass.pronunciation_score);
}

main();

응답 예시

종합 점수는 result.ass_res에, 어절·음소 상세는 result.user_result에 담깁니다. ass_res.words[]는 점수만 제공하며 어절 텍스트를 포함하지 않으므로, 어절 텍스트는 같은 순서의 user_result.results[0].words[]와 대응시켜 사용합니다.

{
  "session_id": "01HXXX…",
  "result": {
    "ass_res": {
      "overall": 87,
      "prosody_score": 82,
      "pronunciation_score": 88,
      "intonation_score": 85,
      "timing_score": 80,
      "loudness_score": 90,
      "err_msg": "",
      "words": [
        { "bSpoken": true, "bSmallLoudness": false,
          "pronunciation": 91, "intonation": 85, "timing": 80, "loudness": 90 }
      ]
    },
    "user_result": {
      "results": [
        { "str": "Hello world", "score": 88,
          "words": [
            { "str": "Hello", "score": 91,
              "phonemes": [ { "str": "HH", "score": 95 }, { "str": "AH", "score": 88 } ] }
          ]
        }
      ]
    },
    "ref_result": { "…": "user_result와 동일한 구조" }
  },
  "statistics": { … },
  "server_time": "2026-02-12T10:30:45Z"
}

응답 REST 응답 본문 — 필드는 결과 구조체를 참고하세요

WebSocket 프로토콜

한 연결에서 아래 순서로 메시지를 주고받습니다. Text 프레임은 JSON 제어 메시지이고, Binary 프레임은 오디오입니다. 아래 요청·응답 필드는 모두 JSON 메시지 기준입니다. 연결 인증은 인증 (API Key)과 브라우저 인증을 참고하세요. 참조 지정 방식에 따라 흐름이 다르며, ② 등록 ID 방식은 ②·③ 단계를 건너뜁니다.

SR · 비교평가 세션 흐름도 — ① 직접 음성 전달 방식

     Client                                 Server
     ──────                                 ──────
 ①  session.start              ─▶   (params.mode: "instance")
                               ◀─  session.started
 ②  [binary reference audio]   ─▶
                               ◀─  data_chunk.ack       (프레임마다 1회)
 ③  command: prepare_reference ─▶
                               ◀─  ref.ok               (실패 시 ref.failed)
                               ◀─  command.ack
 ④  command: start_audio       ─▶
                               ◀─  command.ack
 ⑤  [binary user audio]        ─▶
                               ◀─  data_chunk.ack       (프레임마다 1회)
 ⑥  command: finalize_audio    ─▶
                               ◀─  command.ack
                               ◀─  assessment.result    (최종 결과)
 ⑦  session.end                ─▶
                               ◀─  session.ended

 ※  session.heartbeat          ─▶   (① ~ ⑦ 사이, 30초 권장)
                               ◀─  session.heartbeat.ack

SR · 비교평가 세션 흐름도 — ② 등록 ID 방식

     Client                                 Server
     ──────                                 ──────
 ①  session.start              ─▶   (params.reference_id 등)
                               ◀─  session.started
 ④  command: start_audio       ─▶
                               ◀─  command.ack
 ⑤  [binary user audio]        ─▶
                               ◀─  data_chunk.ack       (프레임마다 1회)
 ⑥  command: finalize_audio    ─▶
                               ◀─  command.ack
                               ◀─  assessment.result    (최종 결과)
 ⑦  session.end                ─▶
                               ◀─  session.ended

 ※  session.heartbeat          ─▶   (① ~ ⑦ 사이, 30초 권장)
                               ◀─  session.heartbeat.ack

① session.start — 세션 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.started

// 클라이언트 → 서버 — ① 직접 음성 전달 방식
{
  "type": "session.start",
  "user_sid": "user-2001",
  "service": "sr",
  "operation": "assess",
  "params": {
    "mode": "instance",
    "reference_text": "Hello world",
    "resource_name": "KONG_ALL",
    "audio_format": { "sample_rate": 16000, "channels": 1, "encoding": "pcm" }
  }
}

// 클라이언트 → 서버 — ② 등록 ID 방식
{
  "type": "session.start",
  "user_sid": "user-2001",
  "service": "sr",
  "operation": "assess",
  "params": {
    "reference_id": "ref-0001",
    "resource_name": "KONG_ALL",
    "audio_format": { "sample_rate": 16000, "channels": 1, "encoding": "pcm" }
  }
}

// 서버 → 클라이언트
{
  "type": "session.started",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "subscription_uuid": "…",
  "subscription_plan_uid": 0,
  "subscription_status": "…",
  "server_time": "2026-02-12T10:30:45Z"
}

② Binary 오디오 프레임 — 참조 음성 전송 ① 방식만

요청 Client → Server · Binary 프레임

응답 Server → Client · data_chunk.ack (프레임마다 1회)

③ command: prepare_reference — 참조 확정 ① 방식만

요청 Client → Server · Text 프레임 (JSON)

응답 1 Server → Client · ref.ok · ref.failed

응답 2 Server → Client · command.ack — 실패 시에는 command.error가 옵니다

// 클라이언트 → 서버
{ "type": "command", "command": "prepare_reference" }

// 서버 → 클라이언트 (1) 참조 준비 결과
{
  "type": "ref.ok",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "mode": "instance",
  "reference": { "ready": true, "audio_bytes": 48044, "text": "Hello world" },
  "message": "reference prepared",
  "server_time": "2026-02-12T10:30:45Z"
}

// 서버 → 클라이언트 (2) 커맨드 수락
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "prepare_reference",
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 90000
}

④ command: start_audio — 오디오 수신 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · command.ack

// 클라이언트 → 서버
{ "type": "command", "command": "start_audio" }

// 서버 → 클라이언트
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "start_audio",
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 85000
}

⑤ Binary 오디오 프레임 — 사용자 음성 전송

요청 Client → Server · Binary 프레임

응답 Server → Client · data_chunk.ack (프레임마다 1회)

// 서버 → 클라이언트
{
  "type": "data_chunk.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "bytes": 16000,
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 412000
}

⑥ command: finalize_audio — 수신 종료 · 비교평가 실행

요청 Client → Server · Text 프레임 (JSON)

응답 1 Server → Client · command.ack

응답 2 Server → Client · assessment.result — 필드는 결과 구조체를 참고하세요

// 클라이언트 → 서버
{ "type": "command", "command": "finalize_audio" }

// 서버 → 클라이언트 (1) 커맨드 수락
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "server_time": "2026-02-12T10:30:46Z",
  "server_processing_time_ns": 310000000
}

// 서버 → 클라이언트 (2) 결과
{
  "type": "assessment.result",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "is_final": true,
  "result": {
    "ass_res": { … },
    "ref_result": { … },
    …
  },
  "statistics": { … },
  "server_time": "2026-02-12T10:30:46Z"
}

⑦ session.end — 세션 종료

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.ended

// 클라이언트 → 서버
{ "type": "session.end", "reason": "completed" }

// 서버 → 클라이언트
{
  "type": "session.ended",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "reason": "completed",
  "statistics": { "frames_received": 2, "audio_bytes": 96088 },
  "server_time": "2026-02-12T10:30:47Z"
}

오류 응답

서버는 상황에 따라 두 종류의 오류 메시지를 보냅니다. 오류 코드는 에러 코드를 참고하세요.

{
  "type": "command.error",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "error": { "code": "INVALID_MESSAGE", "message": "…", "ap_request_id": "…" },
  "server_time": "2026-02-12T10:30:46Z"
}

결과 구조체 REST · WebSocket 공용 · JSON 기준

아래 표는 REST 응답 본문과 WebSocket assessment.result 메시지에 공통으로 적용됩니다. REST는 응답 본문 최상위에, WebSocket은 결과 메시지 본문에 같은 필드가 담기며, WebSocket 메시지에는 type·is_final이 추가됩니다. REST 전용 표시가 있는 필드는 WebSocket 결과 메시지에 없습니다.

억양 분석

REST 프로토콜

발화 음성의 피치(pitch) 곡선을 분석해 억양 데이터를 반환합니다. 결과는 result.Intonation(pitch)과 result.Loudness(energy) 두 개의 float[] 배열이며, 별도의 시간축 필드는 없습니다(등간격 샘플). intonation.result는 WebSocket 메시지의 type이며 REST 단발 응답 본문에는 type 필드가 없습니다.

요청 필드 JSON 기준

호출 샘플

curl -X POST "https://{host}/api/v1/sr/intonation" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'request={"user_sid":"user-2001","params":{}};type=application/json' \
  -F "audio=@speech.wav"

import requests, json

resp = requests.post(
    "https://{host}/api/v1/sr/intonation",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files={
        "request": (None, json.dumps({"user_sid": "user-2001", "params": {}}),
                    "application/json"),
        "audio": ("speech.wav", open("speech.wav", "rb"), "audio/wav"),
    },
)
print(resp.json())

const fs = require("fs");
const path = require("path");

const HOST = "https://{host}";

async function main() {
    const filePath = "./speech.wav";

    const fd = new FormData();

    fd.append(
        "request",
        new Blob(
            [
                JSON.stringify({
                    user_sid: "user-2001",
                    params: {},
                }),
            ],
            { type: "application/json" }
        )
    );

    const file = new Blob([fs.readFileSync(filePath)]);
    fd.append("audio", file, path.basename(filePath));

    const res = await fetch(`${HOST}/api/v1/sr/intonation`, {
        method: "POST",
        headers: {
            Authorization: `Bearer ${API_KEY}`,
        },
        body: fd,
    });

    if (!res.ok) {
        console.error("HTTP Error:", res.status, await res.text());
        return;
    }

    const json = await res.json();
    console.log(json);
}

main();

응답 REST 응답 본문 — 필드는 결과 구조체를 참고하세요

WebSocket 프로토콜

한 연결에서 아래 순서로 메시지를 주고받습니다. Text 프레임은 JSON 제어 메시지이고, Binary 프레임은 오디오입니다. 아래 요청·응답 필드는 모두 JSON 메시지 기준입니다. 연결 인증은 인증 (API Key)과 브라우저 인증을 참고하세요.

SR · 억양 분석 세션 흐름도

     Client                              Server
     ──────                              ──────
 ①  session.start           ─▶
                            ◀─  session.started       (session_id 발급)
 ②  command: start_audio    ─▶
                            ◀─  command.ack
 ③  [binary audio frame]    ─▶
                            ◀─  data_chunk.ack        (프레임마다 1회)
 ④  command: finalize_audio ─▶
                            ◀─  command.ack
                            ◀─  intonation.result     (최종 결과)
 ⑤  session.end             ─▶
                            ◀─  session.ended

 ※  session.heartbeat       ─▶   (① ~ ⑤ 사이, 30초 권장)
                            ◀─  session.heartbeat.ack

① session.start — 세션 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.started

// 클라이언트 → 서버
{
  "type": "session.start",
  "user_sid": "user-2001",
  "service": "sr",
  "operation": "intonation",
  "params": {
    "recognition_mode": "use_epd_with_sil_append",
    "audio_format": { "sample_rate": 16000, "channels": 1, "encoding": "pcm" }
  }
}

// 서버 → 클라이언트
{
  "type": "session.started",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "subscription_uuid": "…",
  "subscription_plan_uid": 0,
  "subscription_status": "…",
  "server_time": "2026-02-12T10:30:45Z"
}

② command: start_audio — 오디오 수신 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · command.ack

// 클라이언트 → 서버
{ "type": "command", "command": "start_audio" }

// 서버 → 클라이언트
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "start_audio",
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 85000
}

③ Binary 오디오 프레임 — 오디오 전송

요청 Client → Server · Binary 프레임

응답 Server → Client · data_chunk.ack (프레임마다 1회)

// 서버 → 클라이언트
{
  "type": "data_chunk.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "bytes": 16000,
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 412000
}

④ command: finalize_audio — 수신 종료 · 억양 분석 실행

요청 Client → Server · Text 프레임 (JSON)

응답 1 Server → Client · command.ack

응답 2 Server → Client · intonation.result — 필드는 결과 구조체를 참고하세요

// 클라이언트 → 서버
{ "type": "command", "command": "finalize_audio" }

// 서버 → 클라이언트 (1) 커맨드 수락
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "server_time": "2026-02-12T10:30:46Z",
  "server_processing_time_ns": 310000000
}

// 서버 → 클라이언트 (2) 결과
{
  "type": "intonation.result",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "is_final": true,
  "result": {
    "Intonation": [ 0.0, 182.4, 185.1, … ],
    "Loudness":   [ 0.0, 0.42, 0.47, … ]
  },
  "statistics": { … },
  "server_time": "2026-02-12T10:30:46Z"
}

⑤ session.end — 세션 종료

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.ended

// 클라이언트 → 서버
{ "type": "session.end", "reason": "completed" }

// 서버 → 클라이언트
{
  "type": "session.ended",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "reason": "completed",
  "statistics": { "frames_received": 1, "audio_bytes": 48044 },
  "server_time": "2026-02-12T10:30:47Z"
}

오류 응답

서버는 상황에 따라 두 종류의 오류 메시지를 보냅니다. 오류 코드는 에러 코드를 참고하세요.

{
  "type": "command.error",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "error": { "code": "INVALID_MESSAGE", "message": "…", "ap_request_id": "…" },
  "server_time": "2026-02-12T10:30:46Z"
}

결과 구조체 REST · WebSocket 공용 · JSON 기준

아래 표는 REST 응답 본문과 WebSocket intonation.result 메시지에 공통으로 적용됩니다. REST는 응답 본문 최상위에, WebSocket은 결과 메시지 본문에 같은 필드가 담기며, WebSocket 메시지에는 type·is_final이 추가됩니다. REST 전용 표시가 있는 필드는 WebSocket 결과 메시지에 없습니다.

자유 발화

REST 프로토콜

요청 필드 JSON 기준

응답은 recognition.result 형식이며, WebSocket 사용 시 recognition.partial 중간 결과를 함께 수신할 수 있습니다.

호출 샘플

curl -X POST "https://{host}/api/v1/stt/transcribe" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'request={"user_sid":"user-2001","params":{"resource_name":"GeneralBase_16KModel","epd":"auto_stop"}};type=application/json' \
  -F "audio=@lecture.wav"

import requests, json

resp = requests.post(
    "https://{host}/api/v1/stt/transcribe",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files={
        "request": (None, json.dumps({
            "user_sid": "user-2001",
            "params": {"resource_name": "GeneralBase_16KModel", "epd": "auto_stop"},
        }), "application/json"),
        "audio": ("lecture.wav", open("lecture.wav", "rb"), "audio/wav"),
    },
)
print(resp.json()["result"]["text"])

const fs = require("fs");
const path = require("path");

const HOST = "https://{host}";

async function main() {
    const filePath = "./speech.wav";

    const fd = new FormData();

    fd.append(
        "request",
        new Blob(
            [
                JSON.stringify({
                    user_sid: "user-2001",
                    params: {
                        resource_name: "EnglishBase_16KModel",
                        epd: "off",
                    },
                }),
            ],
            { type: "application/json" }
        )
    );

    fd.append("audio", new Blob([fs.readFileSync(filePath)]), path.basename(filePath));

    const res = await fetch(`${HOST}/api/v1/stt/transcribe`, {
        method: "POST",
        headers: { Authorization: `Bearer ${API_KEY}` },
        body: fd,
    });

    if (!res.ok) {
        console.error("HTTP Error:", res.status, await res.text());
        return;
    }

    const json = await res.json();
    console.log(json.result.text);
}

main();

응답 REST 응답 본문 — 필드는 결과 구조체를 참고하세요

WebSocket 프로토콜

한 연결에서 아래 순서로 메시지를 주고받습니다. Text 프레임은 JSON 제어 메시지이고, Binary 프레임은 오디오입니다. 아래 요청·응답 필드는 모두 JSON 메시지 기준입니다. 연결 인증은 인증 (API Key)과 브라우저 인증을 참고하세요.

STT · 자유 발화 세션 흐름도

     Client                              Server
     ──────                              ──────
 ①  session.start           ─▶
                            ◀─  session.started       (session_id 발급)
 ②  command: start_audio    ─▶
                            ◀─  command.ack           (STT 스트리밍 시작)
 ③  [binary audio frame]    ─▶
                            ◀─  data_chunk.ack        (프레임마다 1회)
                            ◀─  recognition.partial … (중간 결과, 비동기)
 ④  command: finalize_audio ─▶
                            ◀─  command.ack           (처리 접수)
                            ◀─  recognition.partial … (마무리 중 변경 시)
                            ◀─  recognition.result    (최종 결과)
 ⑤  session.end             ─▶
                            ◀─  session.ended

 ※  session.heartbeat       ─▶   (① ~ ⑤ 사이, 30초 권장)
                            ◀─  session.heartbeat.ack

① session.start — 세션 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.started

// 클라이언트 → 서버
{
  "type": "session.start",
  "user_sid": "user-2001",
  "service": "stt",
  "operation": "transcribe",
  "params": {
    "resource_name": "EnglishBase_16KModel",
    "epd": "chunk_mid",
    "audio_format": { "sample_rate": 16000, "channels": 1, "encoding": "pcm" }
  }
}

// 서버 → 클라이언트
{
  "type": "session.started",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "subscription_uuid": "…",
  "subscription_plan_uid": 0,
  "subscription_status": "…",
  "server_time": "2026-02-12T10:30:45Z"
}

② command: start_audio — 오디오 수신 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · command.ack

// 클라이언트 → 서버
{ "type": "command", "command": "start_audio" }

// 서버 → 클라이언트
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "start_audio",
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 85000
}

③ Binary 오디오 프레임 — 오디오 전송 · 중간 결과 수신

요청 Client → Server · Binary 프레임

응답 Server → Client · data_chunk.ack (프레임마다 1회)

// 서버 → 클라이언트
{
  "type": "data_chunk.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "bytes": 16000,
  "statistics": {
    "audio_size": 16000, "data_chunks": 1, "streaming": true,
    "streaming_end_detected": false, "audio_accepted": true, "ignored_after_epd": false,
    "runtime": "…", "runtime_implementation": "…"
  },
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 412000
}

비동기 응답 Server → Client · recognition.partial

// 서버 → 클라이언트 (오디오 수신 중 수시로)
{
  "type": "recognition.partial",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "is_final": false,
  "result": { … },
  "mid": "Hello my name",
  "statistics": { "streaming": true, "runtime_event": true, "runtime_msg": "progress", "runtime_phase": "…" },
  "server_time": "2026-02-12T10:30:45Z"
}

④ command: finalize_audio — 수신 종료 · 최종 결과

요청 Client → Server · Text 프레임 (JSON)

응답 1 Server → Client · command.ack

응답 2 Server → Client · recognition.result — 필드는 결과 구조체를 참고하세요

// 클라이언트 → 서버
{ "type": "command", "command": "finalize_audio" }

// 서버 → 클라이언트 (1) 처리 접수
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "server_time": "2026-02-12T10:30:46Z",
  "server_processing_time_ns": 120000
}

// 서버 → 클라이언트 (2) 최종 결과
{
  "type": "recognition.result",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "is_final": true,
  "result": { "result_type": "recognition", "text": "Hello my name is Tom", … },
  "statistics": { … },
  "server_time": "2026-02-12T10:30:47Z"
}

⑤ session.end — 세션 종료

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.ended

// 클라이언트 → 서버
{ "type": "session.end", "reason": "completed" }

// 서버 → 클라이언트
{
  "type": "session.ended",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "reason": "completed",
  "statistics": { "frames_received": 12, "audio_bytes": 192000 },
  "server_time": "2026-02-12T10:30:47Z"
}

오류 응답

서버는 상황에 따라 두 종류의 오류 메시지를 보냅니다. 오류 코드는 에러 코드를 참고하세요.

{
  "type": "command.error",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "error": { "code": "INVALID_MESSAGE", "message": "…", "ap_request_id": "…" },
  "server_time": "2026-02-12T10:30:46Z"
}

결과 구조체 REST · WebSocket 공용 · JSON 기준

아래 표는 REST 응답 본문과 WebSocket recognition.result 메시지에 공통으로 적용됩니다. REST는 응답 본문 최상위에, WebSocket은 결과 메시지 본문에 같은 필드가 담기며, WebSocket 메시지에는 type·is_final이 추가됩니다. REST 전용 표시가 있는 필드는 WebSocket 결과 메시지에 없습니다.

파닉스 분석

REST 프로토콜

요청 필드 JSON 기준

호출 샘플

curl -X POST "https://{host}/api/v1/phonics/analyze" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'request={"user_sid":"user-2001","params":{"phonics_type":"word","phonics_text":"about",
       "resource_name":"Phonics_16KModel"}};type=application/json' \
  -F "audio=@phonics.wav"

import requests, json

resp = requests.post(
    "https://{host}/api/v1/phonics/analyze",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files={
        "request": (None, json.dumps({
            "user_sid": "user-2001",
            "params": {
                "phonics_type": "word",
                "phonics_text": "about",
                "resource_name": "Phonics_16KModel",
            },
        }), "application/json"),
        "audio": ("phonics.wav", open("phonics.wav", "rb"), "audio/wav"),
    },
)
result = resp.json()["result"]
print(result["phonics_type"], result["score"])

const fs = require("fs");
const path = require("path");

const HOST = "https://{host}";

async function main() {
    const filePath = "./phonics.wav";

    const fd = new FormData();

    fd.append(
        "request",
        new Blob(
            [
                JSON.stringify({
                    user_sid: "user-2001",
                    params: {
                        phonics_type: "word",
                        phonics_text: "about",
                        resource_name: "Phonics_16KModel",
                    },
                }),
            ],
            { type: "application/json" }
        )
    );

    fd.append("audio", new Blob([fs.readFileSync(filePath)]), path.basename(filePath));

    const res = await fetch(`${HOST}/api/v1/phonics/analyze`, {
        method: "POST",
        headers: { Authorization: `Bearer ${API_KEY}` },
        body: fd,
    });

    if (!res.ok) {
        console.error("HTTP Error:", res.status, await res.text());
        return;
    }

    const json = await res.json();
    console.log(json.result.phonics_type, json.result.score);
}

main();

응답 REST 응답 본문 — 필드는 결과 구조체를 참고하세요

WebSocket 프로토콜

한 연결에서 아래 순서로 메시지를 주고받습니다. Text 프레임은 JSON 제어 메시지이고, Binary 프레임은 오디오입니다. 아래 요청·응답 필드는 모두 JSON 메시지 기준입니다. 연결 인증은 인증 (API Key)과 브라우저 인증을 참고하세요.

Phonics · 파닉스 분석 세션 흐름도

     Client                              Server
     ──────                              ──────
 ①  session.start           ─▶
                            ◀─  session.started       (session_id 발급)
 ②  command: start_audio    ─▶
                            ◀─  command.ack
 ③  [binary audio frame]    ─▶
                            ◀─  data_chunk.ack        (프레임마다 1회)
 ④  command: finalize_audio ─▶
                            ◀─  command.ack
                            ◀─  phonics.result        (최종 결과)
 ⑤  session.end             ─▶
                            ◀─  session.ended

 ※  session.heartbeat       ─▶   (① ~ ⑤ 사이, 30초 권장)
                            ◀─  session.heartbeat.ack

① session.start — 세션 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.started

// 클라이언트 → 서버
{
  "type": "session.start",
  "user_sid": "user-2001",
  "service": "phonics",
  "operation": "analyze",
  "params": {
    "phonics_type": "word",
    "phonics_text": "cat",
    "resource_name": "…",
    "audio_format": { "sample_rate": 16000, "channels": 1, "encoding": "pcm" }
  }
}

// 서버 → 클라이언트
{
  "type": "session.started",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "subscription_uuid": "…",
  "subscription_plan_uid": 0,
  "subscription_status": "…",
  "server_time": "2026-02-12T10:30:45Z"
}

② command: start_audio — 오디오 수신 시작

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · command.ack

// 클라이언트 → 서버
{ "type": "command", "command": "start_audio" }

// 서버 → 클라이언트
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "start_audio",
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 85000
}

③ Binary 오디오 프레임 — 오디오 전송

요청 Client → Server · Binary 프레임

응답 Server → Client · data_chunk.ack (프레임마다 1회)

// 서버 → 클라이언트
{
  "type": "data_chunk.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "bytes": 16000,
  "server_time": "2026-02-12T10:30:45Z",
  "server_processing_time_ns": 412000
}

④ command: finalize_audio — 수신 종료 · 파닉스 분석 실행

요청 Client → Server · Text 프레임 (JSON)

응답 1 Server → Client · command.ack

응답 2 Server → Client · phonics.result — 필드는 결과 구조체를 참고하세요

// 클라이언트 → 서버
{ "type": "command", "command": "finalize_audio" }

// 서버 → 클라이언트 (1) 커맨드 수락
{
  "type": "command.ack",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "server_time": "2026-02-12T10:30:46Z",
  "server_processing_time_ns": 310000000
}

// 서버 → 클라이언트 (2) 결과
{
  "type": "phonics.result",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "is_final": true,
  "result": {
    "phonics_type": "word",
    "text": "cat",
    "score": 87,
    "phonics_count": 3,
    …
  },
  "statistics": { … },
  "server_time": "2026-02-12T10:30:46Z"
}

⑤ session.end — 세션 종료

요청 Client → Server · Text 프레임 (JSON)

응답 Server → Client · session.ended

// 클라이언트 → 서버
{ "type": "session.end", "reason": "completed" }

// 서버 → 클라이언트
{
  "type": "session.ended",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "reason": "completed",
  "statistics": { "frames_received": 1, "audio_bytes": 32044 },
  "server_time": "2026-02-12T10:30:47Z"
}

오류 응답

서버는 상황에 따라 두 종류의 오류 메시지를 보냅니다. 오류 코드는 에러 코드를 참고하세요.

{
  "type": "command.error",
  "session_id": "01HXXXXXXXXXXXXXXXXXXXXXXX",
  "command": "finalize_audio",
  "error": { "code": "INVALID_MESSAGE", "message": "…", "ap_request_id": "…" },
  "server_time": "2026-02-12T10:30:46Z"
}

결과 구조체 REST · WebSocket 공용 · JSON 기준

아래 표는 REST 응답 본문과 WebSocket phonics.result 메시지에 공통으로 적용됩니다. REST는 응답 본문 최상위에, WebSocket은 결과 메시지 본문에 같은 필드가 담기며, WebSocket 메시지에는 type·is_final이 추가됩니다. REST 전용 표시가 있는 필드는 WebSocket 결과 메시지에 없습니다.