{"openapi":"3.0.3","info":{"title":"APICK 오디오 텍스트 변환(STT)","version":"1.0.0","description":"음성 파일 한 개를 올리면 말한 내용을 전체 텍스트와 구간별(시작·끝 시각 포함) 텍스트로 돌려줍니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/stt":{"post":{"summary":"오디오 텍스트 변환(STT)","description":"음성 파일 한 개를 올리면 말한 내용을 전체 텍스트와 구간별(시작·끝 시각 포함) 텍스트로 돌려줍니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"text":{"type":"string","description":"전체 텍스트입니다. 앞에 공백이 붙어 올 수 있으니 필요하면 trim 하세요."},"segments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"구간 번호(0부터)입니다."},"start":{"type":"number","description":"구간 시작 시각(초)입니다."},"end":{"type":"number","description":"구간 끝 시각(초)입니다."},"text":{"type":"string","description":"구간의 텍스트입니다."},"suspect":{"type":"boolean","description":"비음성 문구로 의심되는 구간이면 true입니다. artifact_filter=flag일 때만 담깁니다."}}},"description":"말한 구간별 결과입니다. 시간 순서입니다."},"language":{"type":"string","description":"변환에 사용한 언어 코드입니다."},"duration":{"type":"number","description":"파일 재생시간(초)입니다. 요금 계산 기준입니다."},"success":{"type":"integer","description":"처리 결과입니다. 1: 성공(과금), 0: 실패, 3: 시간 초과(과금 없음)."},"artifact_filter":{"type":"object","description":"비음성 문구 처리 결과입니다. artifact_filter를 보냈을 때만 담깁니다.","properties":{"mode":{"type":"string","description":"요청한 값 flag 또는 remove입니다."},"applied":{"type":"boolean","description":"처리가 적용됐는지 여부입니다. false면 원래 결과 그대로입니다."},"suspect_count":{"type":"integer","description":"표시한 구간 수입니다(flag)."},"removed":{"type":"integer","description":"뺀 구간 수입니다(remove). 남은 구간의 id는 바뀌지 않으므로 번호가 건너뛸 수 있습니다."}}}},"description":"변환 결과"},"api":{"type":"object","properties":{"success":{"type":"boolean","description":"요청을 정상 처리했는지 여부입니다."},"cost":{"type":"integer","description":"이번 요청에서 차감된 포인트입니다."},"ms":{"type":"integer","description":"처리 시간(밀리초)입니다."},"pl_id":{"type":"integer","description":"결제 기록 번호입니다. 문의할 때 함께 알려 주세요."}},"description":"호출 공통 정보"}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"audio":{"type":"string","description":"분석·변환할 오디오 파일입니다. 지원 형식과 최대 길이를 확인하세요. (file)","format":"binary"},"language":{"type":"string","description":"음성에서 추출할 언어 코드입니다. 예: ko(한국어), en(영어), ja(일본어). 생략하면 ko로 인식하며, 실제 발화 언어와 다르면 정확도가 떨어집니다. (string)","example":"ko"},"artifact_filter":{"type":"string","description":"무음·잡음 구간에서 생긴 비음성 문구 처리: flag=구간에 suspect 표시, remove=제거 후 text 재구성. 생략 시 기존과 동일 가능한 값은 2가지입니다. flag = 문제 구간을 삭제하지 않고 suspect 같은 표시만 남기는 값입니다. 원문을 보존해야 할 때 사용합니다. remove = 문제 구간을 제거하고 본문을 다시 구성하는 값입니다. 결과 텍스트가 원문과 달라질 수 있습니다. (string)","enum":["flag","remove"]}},"required":["audio"]}}}}}}},"x-code-tables":[{"title":"오류와 대처","columns":["HTTP","data.error","대처"],"rows":[["400","파일 유형이 맞지 않습니다. mp3, wmv, wav 형식의 파일만 허용됩니다.","파일을 mp3 또는 wav로 변환해 다시 요청하세요."],["424","첨부파일이 없습니다.","파일 필드 이름을 audio로 보냈는지 확인하세요."],["424","artifact_filter 값이 올바르지 않습니다. flag 또는 remove 만 허용됩니다.","artifact_filter를 빼거나 flag·remove 중 하나로 보내세요."],["424","재생시간이 2시간을 초과합니다. 2시간 이내의 오디오 파일만 허용됩니다.","파일을 2시간 이하로 나눠 요청하고 결과를 이어 붙이세요."],["408","처리 시간 초과로 실패했습니다.","data.success가 3입니다. 파일을 짧게 나눠 다시 요청하세요."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}