{"openapi":"3.0.3","info":{"title":"Erroop English TTS API","version":"1.0.0","description":"Kokoro 기반 영어회화용 TTS API.\n\n**인증**: Authorize 버튼에 API 키만 입력하세요. 요청에는 Authorization: Bearer <API_KEY>가 필요합니다.\n\n**CORS**: 모든 출처 허용(Access-Control-Allow-Origin: *). 쿠키 인증은 사용하지 않습니다. API 키는 브라우저 코드에 포함하면 방문자가 볼 수 있으므로 웹앱 백엔드에서 호출하는 구성을 권장합니다.\n\n**데이터**: 입력 문장과 API 키는 로그에 남기지 않습니다. 생성 음성은 최대 5분·32 MiB 범위의 메모리 캐시에만 보관하며 디스크에 저장하지 않습니다.\n\n**연결 예제**: [연동 가이드](/integration.html) · [플레이그라운드](/)"},"servers":[{"url":"/","description":"현재 서버"},{"url":"https://tts.erroop.com","description":"운영 서버"}],"tags":[{"name":"Speech","description":"음성 생성"},{"name":"Metadata","description":"목소리와 서버 상태"}],"paths":{"/v1/audio/speech":{"post":{"tags":["Speech"],"operationId":"createSpeech","summary":"영어 텍스트를 WAV 음성으로 변환","description":"24 kHz · mono · PCM16 WAV를 반환합니다. 최대 1000자, API 키당 분당 60건. 추론 1건과 대기 4건을 처리하며 대기 한도는 15초, 추론 한도는 90초입니다. 같은 문장·목소리·속도는 최대 5분간 메모리 캐시를 재사용합니다. 한국어는 지원하지 않습니다.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechRequest"},"example":{"model":"kokoro","input":"Hi! What is your favorite animal?","voice":"af_heart","speed":0.9,"response_format":"wav"}}}},"responses":{"200":{"description":"생성된 WAV 오디오","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid"},"description":"요청 식별자"},"X-Generation-Ms":{"schema":{"type":"integer"},"description":"추론 소요 시간(ms). 캐시 응답은 0."},"X-Audio-Seconds":{"schema":{"type":"number"},"description":"오디오 재생 길이(초)"},"X-Cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"RateLimit":{"schema":{"type":"string"},"description":"API 키의 분당 요청 한도와 잔여 요청 정보"}},"content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"잘못된 JSON, 영어 이외 입력, 텍스트 길이, 목소리·속도·모델·형식 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer API 키 없음 또는 불일치","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"16 KiB를 초과한 요청 본문","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type이 application/json이 아님","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도·대기열 한도·대기 시간 초과","headers":{"Retry-After":{"description":"재시도까지 대기할 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"음성 생성 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"모델 준비 또는 엔진 복구 중","headers":{"Retry-After":{"description":"재시도까지 대기할 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/speech":{"post":{"tags":["Speech"],"operationId":"createSpeechLegacy","summary":"기존 플레이그라운드 호환 음성 생성","description":"24 kHz · mono · PCM16 WAV를 반환합니다. 최대 1000자, API 키당 분당 60건. 추론 1건과 대기 4건을 처리하며 대기 한도는 15초, 추론 한도는 90초입니다. 같은 문장·목소리·속도는 최대 5분간 메모리 캐시를 재사용합니다. 한국어는 지원하지 않습니다.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacySpeechRequest"},"example":{"text":"Hi! What is your favorite animal?","voice":"af_heart","speed":0.9}}}},"responses":{"200":{"description":"생성된 WAV 오디오","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid"},"description":"요청 식별자"},"X-Generation-Ms":{"schema":{"type":"integer"},"description":"추론 소요 시간(ms). 캐시 응답은 0."},"X-Audio-Seconds":{"schema":{"type":"number"},"description":"오디오 재생 길이(초)"},"X-Cache":{"schema":{"type":"string","enum":["HIT","MISS"]}},"RateLimit":{"schema":{"type":"string"},"description":"API 키의 분당 요청 한도와 잔여 요청 정보"}},"content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"잘못된 JSON, 영어 이외 입력, 텍스트 길이, 목소리·속도·모델·형식 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Bearer API 키 없음 또는 불일치","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"16 KiB를 초과한 요청 본문","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type이 application/json이 아님","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도·대기열 한도·대기 시간 초과","headers":{"Retry-After":{"description":"재시도까지 대기할 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"음성 생성 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"모델 준비 또는 엔진 복구 중","headers":{"Retry-After":{"description":"재시도까지 대기할 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"deprecated":true}},"/v1/voices":{"get":{"tags":["Metadata"],"operationId":"listVoices","summary":"사용 가능한 목소리 조회","responses":{"200":{"description":"미국·영국 영어 목소리 8개","content":{"application/json":{"schema":{"type":"object","properties":{"voices":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}},"default_voice":{"type":"string"},"languages":{"type":"array","items":{"type":"string"}}}}}}}}}},"/healthz":{"get":{"tags":["Metadata"],"operationId":"health","summary":"HTTP 서버 생존 상태","responses":{"200":{"description":"서버 응답 가능"}}}},"/readyz":{"get":{"tags":["Metadata"],"operationId":"ready","summary":"모델 준비 상태","responses":{"200":{"description":"모델 준비 완료"},"503":{"description":"모델 준비 또는 복구 중"}}}},"/api/status":{"get":{"tags":["Metadata"],"operationId":"status","summary":"모델 상태·대기열·제한 조회","responses":{"200":{"description":"status, busy, queued, maxTextLength, authRequired 등"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}},"schemas":{"SpeechRequest":{"type":"object","required":["input"],"properties":{"model":{"type":"string","enum":["kokoro"],"default":"kokoro"},"input":{"type":"string","minLength":1,"maxLength":1000,"description":"읽을 영어 문장. 숫자만 있는 입력은 지원하지 않습니다."},"voice":{"type":"string","enum":["af_heart","af_bella","af_nicole","af_sarah","am_michael","am_puck","bf_emma","bm_george"],"default":"af_heart"},"speed":{"type":"number","minimum":0.5,"maximum":2,"default":1,"description":"어린이 영어 연습은 0.8~1.0부터 테스트해 보세요."},"response_format":{"type":"string","enum":["wav"],"default":"wav"}}},"LegacySpeechRequest":{"type":"object","required":["text"],"properties":{"model":{"type":"string","enum":["kokoro"],"default":"kokoro"},"voice":{"type":"string","enum":["af_heart","af_bella","af_nicole","af_sarah","am_michael","am_puck","bf_emma","bm_george"],"default":"af_heart"},"speed":{"type":"number","minimum":0.5,"maximum":2,"default":1,"description":"어린이 영어 연습은 0.8~1.0부터 테스트해 보세요."},"response_format":{"type":"string","enum":["wav"],"default":"wav"},"text":{"type":"string","minLength":1,"maxLength":1000,"description":"읽을 영어 문장. 숫자만 있는 입력은 지원하지 않습니다."}}},"Voice":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"accent":{"type":"string"},"gender":{"type":"string"},"recommended":{"type":"boolean"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}}}}}