# 한글 발음 변환 AI 숫자·단위·기호·영문이 섞인 한국어 문장을 음성 합성기가 정확히 읽을 수 있는 한글 문장으로 바꿉니다. 5마리는 다섯 마리, 400km는 사백 킬로미터처럼 문맥에 맞는 읽기로 풀어 쓰며, 필요하면 소리 나는 대로 적은 문장도 받을 수 있습니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/llm/text_pronunciation 응답 필드 - `data` (object): 아래 하위 항목을 확인하세요. - `data.text` (string): 변환된 문장 - `data.mode` (string): 적용된 변환 모드 (normalize 또는 phonetic) - `data.input_length` (integer): 과금 기준 입력 글자 수 (앞뒤 공백 제외) - `data.output_length` (integer): 변환 결과 글자 수 - `data.ic_id` (undefined): 아래 하위 항목을 확인하세요. null 허용. - `data.result` (integer): 아래 하위 항목을 확인하세요. - `data.msg` (string): 아래 하위 항목을 확인하세요. - `data.success` (integer): 아래 하위 항목을 확인하세요. - `data.ic_id / result / msg / success` (string): 공통 래퍼 필드 (ic_id=null, result=success=1, msg="") null 허용. - `api` (object): 아래 하위 항목을 확인하세요. - `api.success` (boolean): API 처리 성공 여부 - `api.cost` (integer): 실제 차감된 포인트 (실패 시 0) - `api.ms` (integer): 서버 처리 소요시간(ms) - `api.pl_id` (integer): PaymentLog ID null 허용. ## API 요청: POST /rest/llm/text_pronunciation ### 입력 - `text` (string, 필수): 변환할 원문 텍스트 (최대 2,000자) - `mode` (string, 선택): normalize(기본) 또는 phonetic ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "text": { "type": "string", "description": "변환된 문장" }, "mode": { "type": "string", "description": "적용된 변환 모드 (normalize 또는 phonetic)" }, "input_length": { "type": "integer", "description": "과금 기준 입력 글자 수 (앞뒤 공백 제외)" }, "output_length": { "type": "integer", "description": "변환 결과 글자 수" }, "ic_id": { "nullable": true }, "result": { "type": "integer" }, "msg": { "type": "string" }, "success": { "type": "integer" }, "ic_id / result / msg / success": { "type": "string", "description": "공통 래퍼 필드 (ic_id=null, result=success=1, msg=\"\")", "nullable": true } } }, "api": { "type": "object", "properties": { "success": { "type": "boolean", "description": "API 처리 성공 여부" }, "cost": { "type": "integer", "description": "실제 차감된 포인트 (실패 시 0)" }, "ms": { "type": "integer", "description": "서버 처리 소요시간(ms)" }, "pl_id": { "type": "integer", "description": "PaymentLog ID", "nullable": true } } } } } ``` ### 정적 응답 예시 ```json { "data": { "text": "서울에서 부산까지는 다섯 시간이 넘게 걸리고 거리는 사백 킬로미터쯤 된다. 오 번 버스를 타고 가서 버튼을 다섯 번 누르세요.", "mode": "normalize", "input_length": 63, "output_length": 70, "ic_id": null, "result": 1, "msg": "", "success": 1 }, "api": { "success": true, "cost": 20, "ms": 2874, "pl_id": 901236 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/llm/text_pronunciation' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'text=서울에서 부산까지는 5시간이 넘게 걸리고 거리는 400km쯤 된다. 5번 버스를 타고 가서 버튼을 5번 누르세요.' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("text", "서울에서 부산까지는 5시간이 넘게 걸리고 거리는 400km쯤 된다. 5번 버스를 타고 가서 버튼을 5번 누르세요."); const response = await fetch("https://apick.app/rest/llm/text_pronunciation", { method: "POST", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, body: form, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests parts = [ ("text", (None, "서울에서 부산까지는 5시간이 넘게 걸리고 거리는 400km쯤 된다. 5번 버스를 타고 가서 버튼을 5번 누르세요.")), ] response = requests.request("POST", "https://apick.app/rest/llm/text_pronunciation", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php '서울에서 부산까지는 5시간이 넘게 걸리고 거리는 400km쯤 된다. 5번 버스를 타고 가서 버튼을 5번 누르세요.', ]; $curl = curl_init('https://apick.app/rest/llm/text_pronunciation'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => $form, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## 코드·오류 ## 상세 기능·요금 Method URL POST https://apick.app/rest/llm/text_pronunciation 과금 정책 입력 글자 수에 따라 과금됩니다. 100자까지 20포인트이고, 이후 100자마다 10포인트가 추가됩니다(1포인트 = 1원, 부가세별도). 글자 수는 앞뒤 공백을 뺀 text 길이이며, 변환 결과를 돌려준 요청만 과금합니다. 입력 글자 수과금 1~100자20P 101~200자30P 201~300자40P 901~1,000자110P 1,901~2,000자210P 계산식: 20 + 올림((글자 수 - 100) / 100) × 10 (100자 이하는 20P) 제한사항 구분내용 입력 길이최대 2,000자 (초과 시 400 반환) 최소 잔액선불 회원은 해당 요청의 과금액 이상 잔액이 있어야 합니다. 부족하면 402를 반환합니다. 상태 관리완전 무상태(stateless). 매 요청은 독립적인 단발 호출이며 같은 입력도 매번 새로 처리하고 과금합니다. HTTP 메서드POST 만 허용 변환 모드 mode동작예시 normalize (기본)숫자·단위·기호·영문처럼 읽는 법이 표기에 드러나지 않는 부분만 한글로 풀어 씁니다. 일반 낱말의 표기는 그대로 둡니다.국밥 5그릇을 같이 먹었다. → 국밥 다섯 그릇을 같이 먹었다. phoneticnormalize 를 적용한 뒤 문장 전체를 실제 소리 나는 대로 적습니다.국밥 5그릇을 같이 먹었다. → 국빱 다섣 끄르슬 가치 머걷따. 음성 합성기는 대부분 낱말의 발음 변환을 스스로 하므로 normalize 를 권장합니다. phonetic 은 발음 변환 기능이 없는 합성기에 넣거나 발음 표기 자체가 필요할 때 사용하세요. 어떤 변환을 해주나요? 대상입력결과 수량오징어 5마리, 20명, 5세, 5살오징어 다섯 마리, 스무 명, 오 세, 다섯 살 번호와 횟수5번 버스 / 버튼을 5번오 번 버스 / 버튼을 다섯 번 날짜·시각2026년 10월 2일 오전 9시 30분이천이십육 년 시월 이 일 오전 아홉 시 삼십 분 금액12,500원, 3.5억원만 이천오백 원, 삼억 오천만 원 단위400km, 80km/h, -5℃, 32GB사백 킬로미터, 시속 팔십 킬로미터, 영하 오 도, 삼십이 기가바이트 소수·퍼센트·비율12.5%, 16:9십이 점 오 퍼센트, 십육 대 구 전화번호·숫자 코드010-1234-5678, 인증번호 105028공일공, 일이삼사, 오육칠팔 / 인증번호 일공오공이팔 영문 약어·기술 용어API, CPU, Node.js 22.22.3에이피아이, 씨피유, 노드 제이에스 이십이 점 이십이 점 삼 같은 숫자라도 뒤에 오는 단위와 문맥에 따라 읽는 법을 정합니다. 원문의 의미와 숫자 값, 문장부호, 줄바꿈은 유지하며 변환된 문장만 반환합니다(부가 설명 없음). ## 상세 요청 Header 이름필수설명 Content-TypeOmultipart/form-data; boundary는 클라이언트가 자동 설정합니다. AuthorizationOBearer 인증키 ## 상세 응답 응답 포맷 모든 응답은 공통 래퍼 { data, api } 구조입니다. 과금은 api.cost 에만 표기됩니다. data 이름타입설명 textString변환된 문장 modeString적용된 변환 모드 (normalize 또는 phonetic) input_lengthInteger과금 기준 입력 글자 수 (앞뒤 공백 제외) output_lengthInteger변환 결과 글자 수 ic_id / result / msg / success-공통 래퍼 필드 (ic_id=null, result=success=1, msg="") api 이름타입설명 successBooleanAPI 처리 성공 여부 costInteger실제 차감된 포인트 (실패 시 0) msInteger서버 처리 소요시간(ms) pl_idInteger/nullPaymentLog ID ## 상세 코드·정책 에러 코드 HTTP의미 400text 누락, 2,000자 초과, 지원하지 않는 mode 402잔액 부족 (선불 회원, 해당 요청의 과금액 이상 필요) 500서버 설정 오류 502변환 처리 중 일시적 오류 (과금되지 않으며 다시 요청할 수 있습니다) ## 상세 예제 요청 예시 (cURL) form-data 전체 예제 보기 응답 예시 { "data": { "text": "서울에서 부산까지는 다섯 시간이 넘게 걸리고 거리는 사백 킬로미터쯤 된다. 오 번 버스를 타고 가서 버튼을 다섯 번 누르세요.", "mode": "normalize", "input_length": 63, "output_length": 70, "ic_id": null, "result": 1, "msg": "", "success": 1 }, "api": { "success": true, "cost": 20, "ms": 2874, "pl_id": 901236 } } 요청 예시 (소리 나는 대로 적기) form-data 전체 예제 보기