API 문서: 빠른 시작 및 연동 가이드

작성자 오션캐치 편집팀 · 업데이트됨 2026-11-19

이 문서는 대규모 차량 내비게이션 및 인포테인먼트 팀을 위해 설계된 NavigoVoice 클라우드 TTS API의 기술적 연동 가이드입니다. 텍스트를 음성으로 변환하는 POST 엔드포인트 구조부터 오픈 AI SDK 호환성까지, 실제 개발 환경에서 바로 적용할 수 있는 curl 예시와 필드 설명을 제공합니다.

API 키 발급부터 속도 제한(Rate Limits), 오디오 포맷 선택 기준까지 필요한 모든 기술적 세부 사항을 포함합니다. 기존 오픈 AI SDK의 base_url 변경만으로 대규모 트랜잭션 처리가 가능하도록 설계된 이 API의 작동 원리와 오류 처리 로직을 확인하여 안정적인 음성 생성 파이프라인을 구축하십시오.

API 문서: 빠른 시작 및 연동 가이드

자주 묻는 질문

API 키는 어떻게 발급받나요?

홈페이지의 /get-api-key/ 페이지에서 Google 또는 이메일로 가입하면 API 키가 발급됩니다. 계정에 따라 활성 키가 하나 제공되며, 필요시 새 키를 발행하면 이전 키는 즉시 정지됩니다. 키는 Authorization 헤더에 Bearer 토큰 형태로 사용됩니다.

curl 예시는 어디에 있나요?

curl 예시는 /get-api-key/ 페이지에서 직접 확인할 수 있습니다. 해당 페이지에는 API 키, 잔액, 사용량 정보가 함께 표시되며, 복사하여 바로 사용할 수 있는 준비된 curl 명령어 예제가 제공됩니다.

오픈 AI SDK를 사용할 수 있나요?

네, 공식 OpenAI SDK를 사용할 수 있습니다. base_url을 https://api.oceancatch.info/v1로 변경하고 사이트의 API 키를 설정하면 동일한 요청 형식으로 데이터를 전송할 수 있습니다. 별도의 전용 SDK나 모바일 SDK는 제공되지 않습니다.

base_url을 어떻게 변경하나요?

OpenAI SDK를 사용할 경우 base_url을 https://api.oceancatch.info/v1로 설정해야 합니다. 이렇게 변경하면 official SDK의 speech 엔드포인트를 그대로 활용하여 텍스트를 음성으로 변환할 수 있습니다. 다른 SDK나 plain HTTP 요청에도 이 URL을 사용합니다.

model은 뭐가 있나요?

tts-1과 tts-1-hd 두 가지 모델을 지원합니다. 두 모델은 동일한 엔진을 사용하며 가격도 동일합니다. 모델 선택에 따라 음질이나 가격에 차이가 없으므로, 필요에 따라 선택하여 사용할 수 있습니다.

input 텍스트의 길이는 제한이 있나요?

요청당 최대 4096자까지 입력할 수 있습니다. spaces와 punctuation도 문자 수에 포함됩니다. 4096자를 초과하는 긴 텍스트는 여러 부분으로 나누어 처리한 후 오디오 파일을 연결하여 생성해야 합니다.

voice는 어떻게 선택하나요?

aria, nova, luna, sage, felix, milo, atlas, orion 등 8가지 프리셋 중 하나를 선택합니다. 각 목소리는 특정 성별과 톤을 가지며, GET /v1/voices 엔드포인트를 통해 사용 가능한 보이스 목록을 확인할 수 있습니다.

speed는 어떻게 조절하나요?

speed 파라미터를 0.25에서 4.0 사이의 값으로 설정하여 속도를 조절합니다. 기본값은 1.0이며, 더 빠르거나 느린 음성 생성이 필요할 때 이 값을 조정하여 사용할 수 있습니다.

응답은 어떻게 받나요?

POST 요청에 대한 응답으로 오디오 파일이 직접 반환됩니다. 요청 형식은 OpenAI 스피치 엔드포인트와 동일하므로, SDK 또는 HTTP 클라이언트를 통해 응답 바디에서 오디오 데이터를 처리할 수 있습니다.

오류 코드는 무엇인가요?

구체적인 오류 코드 목록은 문서에 명시되지 않았습니다. 그러나 요청 실패 시 요금이 전액 환불되며, API 키 또는 네트워크 오류 등 일반적인 HTTP 오류 상태 코드가 반환될 수 있습니다.

속도 제한은 어떻게 되나요?

키당 분당 60회 요청까지 가능합니다. 첫 충전 전에는 분당 10회로 제한됩니다. 이 제한을 초과하면 요청이 대기열에 들어갈 수 있습니다.

오디오 포맷은 뭐가 있나요?

mp3, wav, opus, flac, pcm 형식을 지원합니다. response_format 파라미터를 통해 원하는 형식을 지정할 수 있습니다. 각 형식은 용량과 품질에 차이가 있으므로 사용 목적에 맞게 선택해야 합니다.

첫 번째 요청

curl

curl https://api.oceancatch.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.oceancatch.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.oceancatch.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
aria여성
nova여성
luna여성
sage여성
felix남성
milo남성
atlas남성
orion남성
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

API 키 발급

에 대한 소리 파동 일러스트레이션: API 키 발급

API 키 발급은 https://oceancatch.info/get-api-key/ 페이지에서 Google 또는 이메일로 회원가입 후 진행됩니다. 대시보드에서 실시간으로 키, 잔액, 사용량을 확인하고 curl 예시를 바로 복사할 수 있습니다.

Google 로그인 시 $0.50(약 50,000자)의 무료 체험 크레딧이 7일 동안 부여됩니다. 이메일 로그인 시 크레딧은 기본 제공되지 않습니다. 계정은 사이트별로 독립적으로 관리됩니다.

Google 로그인

Google 로그인

Google 계정을 통해 빠르게 로그인할 수 있습니다. 계정 생성 시 $0.50의 무료 크레딧이 자동 적립되며, 이는 약 50,000자의 텍스트 변환에 해당합니다. 이 크레딧은 생성일로부터 7일 동안 유효합니다.

로그인 후 대시보드에서 API 키와 현재 잔액을 즉시 확인할 수 있으며, CURL 예제를 복사하여 테스트할 수 있습니다.

  • Google 계정으로 빠른 인증
  • $0.50 무료 체험 크레딧 자동 지급
  • 7일 간 유효성

이메일 로그인

이메일 로그인

이메일 주소와 비밀번호를 사용하여 계정을 생성할 수 있습니다. 이 방식은 무료 체험 크레딧 없이 시작하며, 이후 USDT 충전으로 잔액을 충전하여 사용할 수 있습니다.

이메일 기반 계정은 독립적으로 관리되며, 별도의 구독이나 최소 사용량이 요구되지 않습니다.

  • 이메일/비밀번호 인증
  • 무료 체험 크레딧 없음
  • USDT 충전 기반

키 생성 및 관리

각 계정에는 활성 API 키가 하나씩 부여됩니다. 필요시 새로운 키를 발급하면 이전 키는 즉시 비활성화됩니다. 이는 보안성을 높이고 키 분산 시 접근을 빠르게 차단할 수 있게 해줍니다.

대시보드에서는 키 상태, 현재 잔액, 생성된 문자 수, 그리고 CURL 예제를 확인할 수 있습니다. 키는 Authorization: Bearer 헤더에 포함되어 요청 인증에 사용됩니다.

  • 활성 키 1개 유지
  • 새 키 발급 시 이전 키 즉시 정지
  • 대시보드에서 키 및 사용량 확인

첫 요청 (curl 예시)

에 대한 소리 파동 일러스트레이션: 첫 요청 (curl 예시)

API 키를 발급받은 후, POST 엔드포인트로 TTS 요청을 시작합니다. 입력 텍스트는 최대 4,096자까지 지원되며, 공백과 문장부호도 문자 수에 포함됩니다.

요청이 성공하면 오디오 파일이 반환되며, 실패 시 비용이 청구되지 않습니다. 초기 속도 제한은 분당 10회로, 충전 후 60회로 확대됩니다.

POST 엔드포인트

TTS 요청은 다음 URL로 전송합니다: POST https://api.oceancatch.info/v1/audio/speech Authorization 헤더에 발급된 API 키를 포함해야 합니다. 형식은 Bearer <YOUR_API_KEY>입니다.

JSON 본문 구조

본문은 JSON 형식으로 전달됩니다. 필수 필드는 model, input, voice입니다. 선택적으로 response_format, speed, language를 설정할 수 있습니다.

예시 요청: { "model": "tts-1", "input": "내비게이션 안내: 현재 차선 변경이 필요합니다.", "voice": "nova", "response_format": "mp3", "speed": 1.0 }

  • model: tts-1 또는 tts-1-hd
  • input: 변환할 텍스트 (최대 4,096자)
  • voice: aria, nova, luna, sage, felix, milo, atlas, orion 중 선택
  • response_format: mp3, wav, opus, flac, pcm
  • speed: 0.25 ~ 4.0
  • language: ISO 코드 (생략 시 자동 감지)

응답 처리

성공 시 HTTP 200 상태 코드와 함께 오디오 바이너리 데이터가 반환됩니다. 실패 시에는 해당 에러 코드와 메시지가 JSON으로 반환됩니다.

반환된 오디오 데이터는 파일로 저장하거나 스트림으로 처리할 수 있습니다. 긴 텍스트의 경우, 클라이언트 측에서 4,096자 단위로 분할하여 생성된 오디오 파일을 연결해야 합니다.

오픈 AI SDK 연동

에 대한 소리 파동 일러스트레이션: 오픈 AI SDK 연동

NavigoVoice API는 OpenAI의 Speech 엔드포인트와 호환되므로, 기존 OpenAI SDK를 그대로 사용할 수 있습니다. 단, base_url을 https://api.oceancatch.info/v1로 변경해야 합니다.

이 방식은 추가 SDK 학습 없이도 대규모 트랜잭션 처리가 가능하게 하며, 인증 키는 Authorization: Bearer 헤더에 포함시켜야 합니다.

base_url 변경

기존 OpenAI 클라이언트에서 base_url을 https://api.oceancatch.info/v1로 설정합니다. API 키는 tts-로 시작하는 고유 키를 사용합니다.

  • - base_url: https://api.oceancatch.info/v1
  • - Auth: Authorization: Bearer tts-...

SDK 사용법

OpenAI Python SDK를 사용하여 client.audio.speech.create() 메서드를 호출합니다. 요청 본문은 model, input, voice 등을 포함해야 합니다.

  • - python-openai 라이브러리 사용
  • - client.audio.speech.create() 호출

호환성 확인

지원되는 모델은 'tts-1'과 'tts-1-hd'이며, 응답 형식은 mp3, wav, opus, flac, pcm을 지원합니다. 속도 제한은 분당 60회입니다.

  • - model: tts-1 또는 tts-1-hd
  • - response_format: mp3, wav, opus, flac, pcm

요청 필드 설명

에 대한 소리 파동 일러스트레이션: 요청 필드 설명

API 호출 시 필수 필드를 정확히 구성해야 일관된 품질의 오디오 파일을 받을 수 있습니다. 모델과 입력 텍스트, 음성 설정을 명확히 지정하면 대규모 내비게이션 시스템에서도 안정적인 결과를 얻을 수 있습니다.

각 필드는 시스템의 처리 로직과 직접 연결되므로, 텍스트의 길이 제한과 음성 속도 범위를 미리 확인해야 합니다. 특히 긴 경로 안내 문구에서는 character 단위의 정밀한 관리가 필요합니다.

model 선택

두 가지 모델을 지원합니다. "tts-1"은 기본 엔진이며 "tts-1-hd"는 고화질 엔진입니다. 두 모델은 오디오 품질과 가격에서 차이가 없으며, 동일하게 $0.01/1,000자 요금이 적용됩니다.

input 텍스트

최대 4,096자까지 입력할 수 있으며, 공백과 구두점도 문자 수에 포함됩니다. 이 제한을 초과하는 긴 안내 문구는 클라이언트에서 여러 부분으로 나누어 요청해야 합니다.

voice 및 speed

8가지 미리 설정된 음성 중 하나를 선택할 수 있으며, 속도 범위는 0.25배에서 4.0배까지 조절 가능합니다. 언어를 명시하지 않으면 스크립트에 따라 자동으로 추론되지만, 비영어권 라틴 문자의 경우 명시적 언어 설정이 권장됩니다.

응답 형식 및 오류

에 대한 소리 파동 일러스트레이션: 응답 형식 및 오류

API는 생성된 오디오 파일을 직접 응답 본문에 포함하여 반환합니다. MP3, WAV, FLAC 등 요청 시 지정한 response_format에 따라 파일이 생성되며, 성공 시 HTTP 200 상태 코드가 반환됩니다. 입력 텍스트는 오디오 생성에만 사용되며 생성된 오디오 파일은 서버에 저장되지 않습니다.

audio 파일 반환

응답 본문에는 바이너리 오디오 데이터가 직접 포함됩니다. 요청 시 선택한 포맷(mp3, wav, opus, flac, pcm)으로 파일이 생성되어 전송됩니다. 긴 텍스트의 경우 분할된 오디오 파일이 반환되므로, 클라이언트 측에서 이를 연결해야 합니다.

에러 코드 처리

합성 실패 시 해당 요청은 무료이며 사용 요금이 반환됩니다. 입력 텍스트가 4096자를 초과하거나 지원되지 않는 언어인 경우 에러가 발생합니다. 정확한 에러 메시지와 함께 HTTP 4xx 또는 5xx 상태 코드를 반환하므로, 로깅을 통해 실패 원인을 파악해야 합니다.

속도 제한

키당 분당 60회 요청이 기본 제한입니다. 첫 충전 전에는 분당 10회로 제한됩니다. 초과 시 HTTP 429 에러가 반환되므로, 재시도 로직에 지수 백오프를 적용해야 합니다. 제한은 충전 즉시 확대되므로 대규모 트랜잭션에도 안정적으로 처리할 수 있습니다.

응답 형식 및 오류

속도 제한 (Rate Limits)

에 대한 소리 파동 일러스트레이션: 속도 제한 (Rate Limits)

API 키당 분당 최대 60개의 요청을 지원합니다. 이는 대규모 내비게이션 시스템에서 안정적으로 오디오 스트림을 생성하기 위한 기본 용량입니다.

초기 계정 생성 후 첫 충전 전에는 분당 10회로 제한됩니다. 이 제한은 충전 처리 후 즉시 해제됩니다.

분당 60회

모든 활성 키는 분당 60건의 요청을 처리할 수 있습니다. 이 용량은 일반적으로 1초당 약 25자의 텍스트 변환에 충분합니다.

초기 10회 제한

초기 단계에서는 분당 10회로 제한됩니다. 이 제한은 시스템 부하를 방지하고 자원을 효율적으로 배분하기 위한 것입니다.

충전 후 확대

USDT(TRC-20)로 최소 $5 이상 충전하면 제한이 즉시 분당 60회로 확대됩니다. 충전은 자동으로 처리되며 몇 분 내에 처리됩니다.

오디오 포맷

에 대한 소리 파동 일러스트레이션: 오디오 포맷

API는 mp3, wav, opus, flac, pcm 등 5가지 포맷을 지원합니다. 선택은 전송 효율과 재생 환경에 따라 결정됩니다. mp3와 opus는 대역폭을 절약하며, wav와 flac은 무손실 품질을 보장합니다. pcm은 Raw 데이터로 즉각 처리가 필요할 때 적합합니다.

대규모 네비게이션 시스템에서는 네트워크 부하를 줄이는 것이 핵심입니다. mp3는 낮은 부하와 넓은 호환성을 제공하므로 일반적인 텍스트 음성 변환에 권장됩니다. 고해상도 오디오가 필요하거나 추가 처리가 필요한 경우 wav나 flac을 선택할 수 있습니다.

mp3, wav, opus, flac, pcm

mp3와 opus는 압축 포맷으로 데이터 크기가 작아 전송 속도가 빠릅니다. wav와 flac은 무손실 포맷으로 원본 음질에 가깝습니다. pcm은 압축되지 않은 Raw 오디오 데이터로, 추가 인코딩 없이 바로 재생할 수 있습니다.

  • mp3: 널리 쓰이는 손실 압축, 낮은 대역폭
  • wav: 무손실, 높은 품질, 큰 파일 크기
  • opus: 효율적인 압축
  • flac: 무손실, 아날로그 원본과 유사
  • pcm: Raw 데이터, 즉각 처리 가능

포맷 선택 기준

대규모 트랜잭션 처리 시 대역폭 비용과 전송 시간을 고려해야 합니다. mp3나 opus는 데이터 전송량이 적어 네트워크 효율이 높습니다. 반면, wav나 flac은 품질을 최우선으로 고려할 때 적합합니다. pcm은 별도의 인코딩 과정이 필요 없는 빠른 처리에 적합합니다.

  • mp3: 일반적인 네비게이션 시스템
  • opus: 모바일 환경 또는 낮은 대역폭
  • wav: 고품질 오디오 저장 필요 시
  • flac: 아날로그 원본과 유사한 품질 필요 시
  • pcm: 추가 인코딩 없이 빠른 처리 필요 시

품질 차이

mp3와 opus는 손실 압축으로 인해 일부 음질 손실이 발생할 수 있습니다. wav와 flac은 무손실 포맷으로 원본 음질을 유지합니다. pcm은 압축되지 않은 Raw 데이터로, 추가 인코딩 없이 바로 재생할 수 있어 품질 저장이 가장 뛰어납니다.

  • mp3: 손실 압축, 일부 음질 손실
  • wav: 무손실, 원본 음질 유지
  • opus: 손실 압축, 효율적 전송
  • flac: 무손실, 고품질 오디오 제공
  • pcm: Raw 데이터

오류 처리 및 재시도

에 대한 소리 파동 일러스트레이션: 오류 처리 및 재시도

API 호출 중 네트워크 불안정이나 일시적인 서버 오류가 발생하면, TTS API는 관련 HTTP 상태 코드와 함께 에러 메시지를 반환합니다. 실패한 요청의 경우 비용이 차감되지 않으므로, 실패 원인을 확인하고 적절히 대응하는 것이 중요합니다.

네트워크 환경에 따라 요청이 실패할 수 있으며, 이 경우 재시도 로직을 구현하여 안정성을 높일 수 있습니다. 서버 오류가 발생하면 일시 대기 후 재시도하는 것이 권장됩니다.

네트워크 오류

네트워크 연결이 불안정하거나 요청이 중단될 경우, 클라이언트는 적절한 오류 처리를 통해 재시도를 수행해야 합니다. 이때, 실패한 요청은 요금이 부과되지 않으므로 안전하게 재시도할 수 있습니다.

  • 네트워크 오류 발생 시 재시도 가능
  • 실패 시 비용 차감 없음

서버 오류

서버에서 일시적인 오류가 발생하면, HTTP 상태 코드를 통해 해당 오류를 식별할 수 있습니다. 서버 오류가 발생하면, 적절한 대기 후 재시도를 통해 성공적으로 처리할 수 있습니다.

  • 일시적인 서버 오류는 재시도로 해결 가능
  • 서버 오류 발생 시 대기 후 재시도 권장

재시도 로직

재시도 로직은 네트워크 오류와 서버 오류 모두에서 유용하게 사용됩니다. 적절한 대기 시간을 설정하여 재시도하면, 일시적인 오류를 해결할 수 있으며, 실패 시에도 비용을 안전하게 처리할 수 있습니다.

재시도 로직을 구현할 때는 재시도 횟수와 대기 시간을 적절히 조절하여, 서버에 과도한 부하가 가지 않도록 주의해야 합니다. 이를 통해 안정적인 API 호출이 가능합니다.

  • 적절한 대기 시간 설정 권장
  • 재시도 횟수와 대기 시간 조절 필요

8개 음성 듣기

아래의 각 샘플은 동일한 문장을 이 API로 생성한 것입니다. 이 정보는 요금 계산과 과금 내역 증명을 위해 사용되며, 텍스트 내용과 직접 연결되어 장기 보관되지 않습니다.

음성 아바타 aria
aria여성
음성 아바타 nova
nova여성
음성 아바타 luna
luna여성
음성 아바타 sage
sage여성
음성 아바타 felix
felix남성
음성 아바타 milo
milo남성
음성 아바타 atlas
atlas남성
음성 아바타 orion
orion남성

23개 언어

모든 음성은 이 언어들을 구사합니다.

출처 및 참고 자료

  1. Wikipedia
  2. LibriVox public-domain audiobooks
  3. FFmpeg documentation
  4. OpenAI API reference: create speech
  5. openai-node on GitHub
  6. MDN: Web Speech API
  7. Creative Commons Attribution 4.0
  8. Node.js documentation
  9. Tether (USDT)
  10. ISO 639 language codes
  11. curl documentation
  12. LibriTTS-R corpus (OpenSLR 141)

이 사이트의 다른 콘텐츠