tts (Text-To-Speech)

개요

Clova Premium Voice API는 음성으로 변환할 텍스트와 음색, 속도, 감정 등을 파라미터로 입력받아 음성을 합성하여 그 결과를 반환하는 HTTP 기반의 REST API입니다.

요청

curl -i -X POST \
	-H "Content-Type:application/x-www-form-urlencoded" \
	-H "X-NCP-APIGW-API-KEY-ID:{애플리케이션 등록 시 발급받은 client id값}" \
	-H "X-NCP-APIGW-API-KEY:{애플리케이션 등록 시 발급받은 client secret값}" \
	-d 'speaker={목소리 종류}&text={텍스트}&volume={볼륨}&speed={음성 재생 속도}&pitch={피치}&emotion={감정}' \
 'https://naveropenapi.apigw.ntruss.com/voice-premium/v1/tts'

요청 파라미터

파라미터 이름 타입 설명 기본값 필수 여부
speaker string 음성 합성에 사용할 목소리 종류. 현재는 한국어 여성만 지원합니다.
  • nara : 한국어, 여성 음색
없음 Y
text string 음성 합성할 문장. UTF-8 인코딩된 텍스트만 지원합니다. CSS Premium API는 최대 200 자의 텍스트까지 음성 합성을 지원합니다. 기호나 괄호 안의 텍스트는 읽지 않습니다. 없음 Y
volume integer 음성 볼륨. -5에서 5 사이의 정수 값이며, -5 이면 0.5 배 낮은 볼륨이고 5 이면 1.5 배 더 큰 볼륨입니다. 0 이면 정상 볼륨의 목소리로 음성을 합성합니다. 0 N
speed integer 음성 속도. -5에서 5 사이의 정수 값이며, -5 이면 2 배 빠른 속도이고 5 이면 0.5 배 더 느린 속도입니다. 0 이면 정상 속도의 목소리로 음성을 합성합니다. 0 N
pitch integer 음성 피치. -5에서 5 사이의 정수 값이며, -5 이면 1.2 배 높은 피치이고 5 이면 0.8 배 더 낮은 피치입니다. 0 이면 정상 피치의 목소리로 음성을 합성합니다. 0 N
emotion integer 음성 감정. 0에서 2 사이의 정수 값이며 0 은 기본, 1 은 어두운, 2 는 밝은 음성입니다. 0 N
format string 음성 포멧. wav 혹은 mp3를 입력하세요. mp3 N

요청 헤더

헤더명 설명
X-NCP-APIGW-API-KEY-ID 앱 등록 시 발급받은 Client ID
X-NCP-APIGW-API-KEY-ID:{Client ID}
X-NCP-APIGW-API-KEY 앱 등록 시 발급 받은 Client Secret
X-NCP-APIGW-API-KEY:{Client Secret}
Content-Type application/x-www-form-urlencoded로 고정
Content-Type: application/x-www-form-urlencoded

요청 바디

  • 해당 API 는 요청 바디를 필요로 하지 않습니다.

응답

응답 바디

  • MP3 바이너리 데이터

예시

요청 예시

curl -i -X POST \
	-H "Content-Type:application/x-www-form-urlencoded" \
	-H "X-NCP-APIGW-API-KEY-ID:{애플리케이션 등록 시 발급받은 client id값}" \
	-H "X-NCP-APIGW-API-KEY:{애플리케이션 등록 시 발급받은 client secret값}" \
	-d 'speaker=nara&text=만나서 반갑습니다&volume=0&speed=0&pitch=0&emotion=0&format=mp3' \
 'https://naveropenapi.apigw.ntruss.com/voice-premium/v1/tts'

응답 예시

[HTTP Response Header]
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 28 Sep 2016 06:51:49 GMT
Content-Type: audio/mpeg;charset=utf-8
Content-Length: 19794
Connection: keep-alive
Keep-Alive: timeout=5
X-QUOTA: 1

[HTTP Response Body]
{MP3 형식의 바이너리 데이터}

API 예제

// 네이버 음성합성 Open API 예제
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.util.Date;

public class APIExamTTS {

    public static void main(String[] args) {
        String clientId = "YOUR_CLIENT_ID";//애플리케이션 클라이언트 아이디값";
        String clientSecret = "YOUR_CLIENT_SECRET";//애플리케이션 클라이언트 시크릿값";
        try {
            String text = URLEncoder.encode("만나서 반갑습니다.", "UTF-8"); // 13자
            String apiURL = "https://naveropenapi.apigw.ntruss.com/voice-premium/v1/tts";
            URL url = new URL(apiURL);
            HttpURLConnection con = (HttpURLConnection)url.openConnection();
            con.setRequestMethod("POST");
            con.setRequestProperty("X-NCP-APIGW-API-KEY-ID", clientId);
            con.setRequestProperty("X-NCP-APIGW-API-KEY", clientSecret);
            // post request
            String postParams = "speaker=nara&volume=0&speed=0&pitch=0&emotion=0&format=mp3&text=" + text;
            con.setDoOutput(true);
            DataOutputStream wr = new DataOutputStream(con.getOutputStream());
            wr.writeBytes(postParams);
            wr.flush();
            wr.close();
            int responseCode = con.getResponseCode();
            BufferedReader br;
            if(responseCode==200) { // 정상 호출
                InputStream is = con.getInputStream();
                int read = 0;
                byte[] bytes = new byte[1024];
                // 랜덤한 이름으로 mp3 파일 생성
                String tempname = Long.valueOf(new Date().getTime()).toString();
                File f = new File(tempname + ".mp3");
                f.createNewFile();
                OutputStream outputStream = new FileOutputStream(f);
                while ((read =is.read(bytes)) != -1) {
                    outputStream.write(bytes, 0, read);
                }
                is.close();
            } else {  // 오류 발생
                br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
                String inputLine;
                StringBuffer response = new StringBuffer();
                while ((inputLine = br.readLine()) != null) {
                    response.append(inputLine);
                }
                br.close();
                System.out.println(response.toString());
            }
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}
// 네이버 음성합성 Open API 예제
<?php
  $client_id = "YOUR_CLIENT_ID";
  $client_secret = "YOUR_CLIENT_SECRET";
  $encText = urlencode("반갑습니다.");
  $postvars = "speaker=nara&volume=0&speed=0&pitch=0&emotion=0&format=mp3&text=".$encText;
  $url = "https://naveropenapi.apigw.ntruss.com/voice-premium/v1/tts";
  $is_post = true;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch,CURLOPT_POSTFIELDS, $postvars);
  $headers = array();
  $headers[] = "X-NCP-APIGW-API-KEY-ID: ".$client_id;
  $headers[] = "X-NCP-APIGW-API-KEY: ".$client_secret;
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec ($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  echo "status_code:".$status_code."<br />";
  curl_close ($ch);
  if($status_code == 200) {
    //echo $response;
    $fp = fopen("tts.mp3", "w+");
    fwrite($fp, $response);
    fclose($fp);
    echo "<a href='tts.mp3'>TTS재생</a>";
  } else {
    echo "Error 내용:".$response;
  }
?>
// 네이버 음성합성 Open API 예제
var express = require('express');
var app = express();
var client_id = 'YOUR_CLIENT_ID';
var client_secret = 'YOUR_CLIENT_SECRET';
var fs = require('fs');
app.get('/tts', function(req, res) {
  var api_url = 'https://naveropenapi.apigw.ntruss.com/voice-premium/v1/tts';
  var request = require('request');
  var options = {
    url: api_url,
    form: { speaker: 'nara', volume: '0', speed: '0', pitch: '0', emotion: '0', text: '좋은 하루 되세요', format: 'mp3' },
    headers: { 'X-NCP-APIGW-API-KEY-ID': client_id, 'X-NCP-APIGW-API-KEY': client_secret },
  };
  var writeStream = fs.createWriteStream('./tts1.mp3');
  var _req = request.post(options).on('response', function(response) {
    console.log(response.statusCode); // 200
    console.log(response.headers['content-type']);
  });
  _req.pipe(writeStream); // file로 출력
  _req.pipe(res); // 브라우저로 출력
});
app.listen(3000, function() {
  console.log('http://127.0.0.1:3000/tts app listening on port 3000!');
});
// 네이버 음성합성 Open API 예제
import os
import sys
import urllib.request
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"
encText = urllib.parse.quote("반갑습니다 네이버")
data = "speaker=nara&volume=0&speed=0&pitch=0&emotion=0&format=mp3&text=" + encText;
url = "https://naveropenapi.apigw.ntruss.com/voice-premium/v1/tts"
request = urllib.request.Request(url)
request.add_header("X-NCP-APIGW-API-KEY-ID",client_id)
request.add_header("X-NCP-APIGW-API-KEY",client_secret)
response = urllib.request.urlopen(request, data=data.encode('utf-8'))
rescode = response.getcode()
if(rescode==200):
    print("TTS mp3 저장")
    response_body = response.read()
    with open('1111.mp3', 'wb') as f:
        f.write(response_body)
else:
    print("Error Code:" + rescode)
# -*- coding: utf-8 -*-
import os
import sys
import urllib
import urllib2
reload(sys)
sys.setdefaultencoding('utf-8')
client_id = "YOUR_CLIENT_ID" # 애플리케이션 클라이언트 아이디값"
client_secret = "YOUR_CLIENT_SECRET" # 애플리케이션 클라이언트 시크릿값"
text = unicode("반갑습니다 네이버") # 음성 합성할 문장
speaker = "nara" # 음성 합성에 사용할 목소리 종류
speed = "0" # 음성 재생 속도
volume = "0" # 음성 볼륨
pitch = "0" # 음성 피치
emotion = "0" # 음성 감정
fmt = "mp3" # 음성 포멧
val = {
    "speaker": speaker,
    "volume": volume,
    "speed":speed,
    "pitch": pitch,
    "emotion": emotion,
    "text":text,
    "format": fmt
}
data = urllib.urlencode(val)
url = "https://naveropenapi.apigw.ntruss.com/voice-premium/v1/tts"
headers = {
    "X-NCP-APIGW-API-KEY-ID" : client_id,
    "X-NCP-APIGW-API-KEY" : client_secret
}
request = urllib2.Request(url, data, headers)
response = urllib2.urlopen(request)
rescode = response.getcode()
if(rescode==200):
    print("TTS mp3 save")
    response_body = response.read()
    with open('1111.mp3', 'wb') as f:
        f.write(response_body)
else:
    print("Error Code:" + rescode)

// 네이버 음성합성 Open API 예제
using System;
using System.Net;
using System.Text;
using System.IO;

namespace NaverAPI_Guide
{
    public class APIExamTTS
    {
        static void Main(string[] args)
        {
            string text = "좋은 하루 되세요."; // 음성합성할 문자값
            string url = "https://naveropenapi.apigw.ntruss.com/voice-premium/v1/tts";
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
            request.Headers.Add("X-NCP-APIGW-API-KEY-ID", "YOUR-CLIENT-ID");
            request.Headers.Add("X-NCP-APIGW-API-KEY", "YOUR-CLIENT-SECRET");
            request.Method = "POST";
            byte[] byteDataParams = Encoding.UTF8.GetBytes("speaker=nara&volume=0&speed=0&pitch=0&emotion=0&format=mp3&text=" + text);
            request.ContentType = "application/x-www-form-urlencoded";
            request.ContentLength = byteDataParams.Length;
            Stream st = request.GetRequestStream();
            st.Write(byteDataParams, 0, byteDataParams.Length);
            st.Close();
            HttpWebResponse response = (HttpWebResponse)request.GetResponse();
            string status = response.StatusCode.ToString();
            Console.WriteLine("status="+ status);
            using (Stream output = File.OpenWrite("c:/tts.mp3"))
            using (Stream input = response.GetResponseStream())
            {
                input.CopyTo(output);
            }
            Console.WriteLine("c:/tts.mp3 was created");
        }
    }
}
curl "https://naveropenapi.apigw.ntruss.com/voice-premium/v1/tts" \
	-d "speaker=nara&volume=0&speed=0&pitch=0&emotion=0&format=mp3&text=만나서 반갑습니다." \
	-H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id 값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret 값}" -v \
		> out.mp3

오류 코드

HttpStatusCode ErrorCode ErrorMessage Description
400 VS01 speaker parameter is needed. speaker 파라미터가 누락되었습니다.
400 VS02 Unsupported speaker. 지원하지 않는 speaker입니다.
400 VS05 text parameter is needed. text 파라미터가 누락되었습니다.
400 VS06 text parameter exceeds max length. text 파라미터에 입력할 수 있는 최대 글자 수를 초과했습니다.
400 VS07 Unsupported volume. 지원하지 않는 볼륨입니다.
400 VS08 Unsupported pitch. 지원하지 않는 피치입니다.
400 VS10 text parameter check. text 파라미터를 확인해주세요.
400 VS11 Unsupported format. 지원하지 않는 포맷입니다.
400 VS14 Unsupported emotion value. 유효한 emotion 값이 아닙니다.
500 VS99 Internal server error 서버 내부 오류가 발생했습니다. 고객지원을 통해 문의하시면 신속히 조치하겠습니다.