VoiceGen AI API

텍스트를 자연스러운 음성으로 변환하는 REST API입니다. XTTS v2 기반 다국어 TTS와 음성 클로닝을 지원합니다.

Base URL: https://vg.kiam.kr

🔒 인증

모든 API 요청에는 X-API-Key 헤더에 발급받은 API 키를 포함해야 합니다.

X-API-Key: vg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API 키는 대시보드에서 발급할 수 있습니다.

⏳ 사용 한도

플랜	월 한도	1회 최대	클로닝
Free	10,000자	500자	불가
Starter	100,000자	1,000자	1개
Pro	500,000자	2,000자	무제한
Business	2,000,000자	5,000자	무제한

🎙 POST /api/v1/generate.php

POST /api/v1/generate.php

텍스트를 선택한 목소리로 음성(WAV)으로 변환합니다.

요청 파라미터 (multipart/form-data)

파라미터	타입	필수	설명
text	string	필수	변환할 텍스트 (최대 플랜 한도)
voice_id	string	선택	목소리 ID (기본: ko_female_1)
speed	float	선택	재생 속도 0.5~2.0 (기본: 1.0)
language	string	선택	언어 코드: ko, en, ja, zh, fr, de (기본: ko)

응답

성공 시 audio/wav 바이너리 데이터를 반환합니다.

헤더	설명
X-VG-Chars	이번 요청에서 사용된 글자수
X-VG-Remaining	이번 달 남은 글자수

curl -X POST https://vg.kiam.kr/api/v1/generate.php \
  -H "X-API-Key: vg_your_api_key" \
  -F "text=안녕하세요, VoiceGen AI입니다." \
  -F "voice_id=ko_female_1" \
  -F "speed=1.0" \
  -o output.wav

🎤 POST /api/v1/clone.php

POST /api/v1/clone.php

업로드한 레퍼런스 오디오(내 목소리)로 텍스트를 읽어줍니다. STARTER 이상 플랜 필요.

요청 파라미터 (multipart/form-data)

파라미터	타입	필수	설명
text	string	필수	읽어줄 텍스트
reference_audio	file	필수	내 목소리 파일 (WAV/MP3/OGG, 5초 이상, 최대 20MB)
language	string	선택	언어 코드 (기본: ko)
speed	float	선택	속도 0.5~2.0 (기본: 1.0)

curl -X POST https://vg.kiam.kr/api/v1/clone.php \
  -H "X-API-Key: vg_your_api_key" \
  -F "text=이것은 내 목소리로 읽는 텍스트입니다." \
  -F "reference_audio=@my_voice.wav" \
  -F "language=ko" \
  -o cloned.wav

♫ GET /api/v1/voices.php

GET /api/v1/voices.php

사용 가능한 목소리 목록을 반환합니다.

응답 예시

{"voices":[
  {"id":"ko_female_1","name":"수아","lang":"ko","gender":"female"},
  {"id":"ko_male_1","name":"민준","lang":"ko","gender":"male"},
  {"id":"en_female_1","name":"Emma","lang":"en","gender":"female"},
  ...
],"count":6}

⚠ 오류 코드

HTTP 코드	의미
400	잘못된 요청 (파라미터 오류, 글자수 초과)
401	API 키 없음 또는 유효하지 않음
403	플랜 미지원 기능 (클로닝은 STARTER 이상)
429	월 사용 한도 초과
500	서버 내부 오류
503	GPU 서비스 미준비

📄 전체 예제

Python

import requests

API_KEY = "vg_your_api_key"
BASE_URL = "https://vg.kiam.kr"

# 기본 음성 생성
resp = requests.post(
    f"{BASE_URL}/api/v1/generate.php",
    headers={"X-API-Key": API_KEY},
    data={"text": "안녕하세요!", "voice_id": "ko_female_1"}
)
with open("output.wav", "wb") as f:
    f.write(resp.content)

# 음성 클로닝
with open("my_voice.wav", "rb") as ref:
    resp = requests.post(
        f"{BASE_URL}/api/v1/clone.php",
        headers={"X-API-Key": API_KEY},
        data={"text": "클로닝 테스트입니다.", "language": "ko"},
        files={"reference_audio": ref}
    )
with open("clone.wav", "wb") as f:
    f.write(resp.content)

JavaScript (Node.js)

const FormData = require('form-data');
const fetch = require('node-fetch');
const fs = require('fs');

const API_KEY = 'vg_your_api_key';
const form = new FormData();
form.append('text', '안녕하세요!');
form.append('voice_id', 'ko_female_1');

const res = await fetch('https://vg.kiam.kr/api/v1/generate.php', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, ...form.getHeaders() },
  body: form
});
fs.writeFileSync('output.wav', Buffer.from(await res.arrayBuffer()));