1. Selvy CloudAPI 개요

이 문서는 Selvy CloudAPI를 사용하여 서비스 및 어플리케이션을 개발하기 위한 가이드 문서입니다. 현재는 음성합성을 위한 Selvy TTS를 지원하고 있으며, 향후 AI기술이 적용된 다양한 서비스가 추가될 예정입니다.

문서내에 Selvy CloudAPI의 구성, 통신방식 및 호출단계, 인증 방법 및 절차, Selvy TTS API와 에러코드에 대한 설명을 포함하고 있습니다.

최종수정일: 2020년 4월 6일

2. Selvy CloudAPI 구성

Selvy Cloud API 에서는 아래와 같은 Cloud Service를 제공하고 있습니다.

Cloud Service 명	설명
Selvy TTS (음성합성 서비스)	문자로 받아들인 내용을 음성으로 변환시켜주는 서비스입니다.

3. 통신 방식

Selvy CloudAPI는 HTTP를 이용하여 통신합니다. 세부 지원항목은 아래와 같습니다.

항목	설명
Method	HTTP Method 중 정보를 가져오는 “GET”과 입력하는 “POST”를 사용하며, W3C에서 정한 규격을 따르고 있습니다.
Header	요청에 대해 설명하는 메타정보를 포함합니다. 인증 Token을 전달하거나 응답 받을 컨텐츠 유형을 지정할 수 있습니다.
Status Code	HTTP 요청에 대한 결과를 나타내는 코드로, 잘못 요청 하였을 경우 400 Bad Request, 서버에 오류가 있을 경우 500을 반환합니다.

4. 호출 단계

Selvy CloudAPI를 사용하기 위하여 먼저 인증 절차를 수행하여야 하며, 인증시 전달받은 Access Token을 이용하여 API 요청/응답 단계를 수행하여야 서비스를 정상적으로 이용할 수 있습니다.

Step1. 인증	Step2. API 요청/응답
- Selvy CloudAPI를 사용하기 위해서는 인증절차가 선행되어야 합니다. - 인증은 OAuth2.0 방식을 이용하고 있으며, 인증을 통해 획득한 Access Token 을 이용하여 API 기능 수행이 가능합니다.	- Selvy TTS 을 포함하여 Selvy Cloud API 에서 제공하는 Cloud Service의 요청에 대한 처리를 수행합니다. - 각 API의 특성에 따라 요청, 응답의 절차가 다를 수 있습니다. 이는 해당 API 의 상세 개발 안내를 참고하십시오.

Step1. 인증

Step2. API 요청/응답

- Selvy CloudAPI를 사용하기 위해서는 인증절차가 선행되어야 합니다.

- 인증은 OAuth2.0 방식을 이용하고 있으며, 인증을 통해 획득한 Access Token 을 이용하여 API 기능 수행이 가능합니다.

- Selvy TTS 을 포함하여 Selvy Cloud API 에서 제공하는 Cloud Service의 요청에 대한 처리를 수행합니다.

- 각 API의 특성에 따라 요청, 응답의 절차가 다를 수 있습니다. 이는 해당 API 의 상세 개발 안내를 참고하십시오.

5. 인증 방법 및 절차

인증은 인가된 사용자가 Selvy CloudAPI 서비스를 요청하고 있는지 확인하는 절차입니다. Cloud Service를 사용하기 위하여 필수적으로 선행되어야 합니다.
5.1 인증 방법

인증 절차를 수행하여 인증이 올바르다면 Access Token 을 발급받아 API 사용이 가능합니다.

접근권한은 표준화된 인증방식인 OAuth2.0를 이용하고 있습니다. 적용된 OAuth2.0의 인증방식은 Client Credentials Flow를 사용하여, Client가 적합한지 여부만 판단합니다.
5.2 인증 절차
Application(Client)
- - Application는 자격증명(Client ID, Client Secret)을 Auth Server로 전송하여 Access Token을 요청합니다.
- - 발급 받은 Access Token을 이용하여 Cloud Service를 요청합니다.
Auth Server(Service API)
- - Application이 전달한 자격증명(Client ID, Client Secret)을 확인하여 인가된 사용자의 경우 접근권한이 부여된 Access Token을 발급합니다.
- - Application의 Cloud Service 사용 요청에 대하여 Access Token을 확인하고, 적합한 권한을 갖고 있을 경우 Resource Server로 요청을 전달합니다.
Resource Server(Cloud Service Server)
- - 인가된 사용요청에 대하여 Cloud Service(Selvy TTS)를 수행합니다.

5.3 Access Token

Application이 인증절차에 의하여 발급 받은 Access Token이 있으면, Token이 만료되거나 취소 되기 전까지 부여된 권한의 Cloud Service를 이용할 수 있습니다.

5.3.1 요청

HTTP 요청 URI

POST /oauth/token

요청 Host 구성요소

https://{client_id}:{client_secret}@{domain}/oauth/token?grant_type=client_credentials&scope={service_name}

Property	Type	Description	Notes
client_id	string	Client ID	Selvy CloudAPI 운영자를 통하여 전달 받은 자격증명
client_secret	string	Client Secret	Selvy CloudAPI 운영자를 통하여 전달 받은 자격증명
domain	string	Auth Server 도메인	요청 서버의 도메인

요청 Parameters

Property	Type	Description	Notes
grant_type	string	인증방법에 대한 고정문자열	Selvy Cloud API 에서는 Client Credentials Flow 방식(“client_credentials”)만을 사용
scope	string	Application의 권한 범위를 나태내는 고정문자열	service_name은 Cloud Service의 서비스 정책으로 정의되며, 정확한 명칭은 운영자를 통하여 전달 tts : Selvy TTS

5.3.2 응답

응답 Payloads - application/json

{
	"access_token": string,
	"token_type": string,
	"expires_in": integer,
	"scope": string 
}

Property	Type	Description	Notes
access_token	string	권한이 부여된 Token	-
token_type	string	Token의 유형	항상 “Bearer”로 응답
expires_in	integer	Access Token의 만료시간	Auth Server의 설정에 따라 결정됨 무제한 또는 초단위로 설정이 가능
scope	string	access_token을 통하여 접근할 수 있는 Cloud Service의 권한 범위	Cloud Service의 서비스 정책으로 정의되며, 정확한 명칭의 의미는 운영자를 통하여 전달

6. Selvy TTS API

Selvy TTS(음성합성) API 사용을 위한 상세 개발 안내입니다.

6.1 Flow

Selvy TTS Cloud Service Flow 는 다음과 같습니다.

Step1. Voices	Step2. Speech synthesis
Application이 요청한 언어에 대하여 사용 가능한 화자정보를 생성하여 반환	Application이 요청한 정보와 텍스트에 대하여 음성합성을 수행하고, 생성된 합성음을 반환

6.2 Voices

Application이 요청한 언어에 대하여 사용 가능한 화자정보를 생성하여 반환합니다. 전체 지원 언어 및 화자는 6.2.1 Voice 지원현황 참고하십시오.

HTTP 요청 URI

GET /v2/tts/voices

요청 예시

GET /v2/tts/voices?languageCode=ko-KR HTTP/1.1
Authorization: Bearer ef2acb39-229d-42eb-bb13-1ef7d27f5c0b
Host: cloud.selvy.ai

HTTP Header

Field Name	Mandatory	Example	Description
Authorization	Y	Bearer ef2acb39-229d-42eb-bb13-1ef7d27f5c0b	- HTTP 인증을 위한 인증 자격증명에 사용됩니다. - Token Type(“Bearer”)과 함께 인증서버로부터 획득한 Access Token 을 입력합니다.

요청 Parameters

Name	Type	Mandatory	Default	Example	Notes
languageCode	string	Y	-	ko-KR	- 지정한 언어 코드에 해당하는 화자 정보만 출력 6.2.1 Voice 지원현황 참고

요청 Payloads

Node	Properties	Type	Mandatory	Description	Remarks
-	-	-	-	-	-

응답 예시

{
	"voices": [{
		"name": "Hyejin",
		"gender": "Female",
		"id": "Hyejin",
		"languageCode": "ko-KR",
		"languageName": "Korean"
	}, {
		"name": "Yujin",
		"gender": "Female",
		"id": "Yujin",
		"languageCode": "ko-KR",
		"languageName": "Korean"
	}, {
		"name": "Aram",
		"gender": "Female",
		"id": "Aram",
		"languageCode": "ko-KR",
		"languageName": "Korean"
	}]
}

응답 Header

Field Name	Mandatory	Example	Description
-	-	-	-

응답 Payloads

Node	Properties	Type	Mandatory	Description	Remarks
voices	-	node	Y	-	-
	name	string	Y	화자 아이디에 대한 읽기 가능한 표현	-
	gender	string	Y	화자의 성별	-
	id	string	Y	음성 합성에 사용되는 화자 아이디	-
	languageCode	string	Y	화자가 나타내는 언어 코드	-
	languageName	string	Y	언어 코드에 대한 읽기 가능한 표현	-

6.2.1 Voice 지원현황

name	gender	id		languageCode	languageName
name	gender	Basic	High-Quality USS	languageCode	languageName
Yujin	Female	Yujin	Yujin-H	ko-KR	Korean
Minjun	Male	Minjun	Minjun-H	ko-KR	Korean
Aram	child	Aram	Aram-H	ko-KR	Korean
Gichan	Male	Gichan	Gichan-H	ko-KR	Korean
Sujin	Female	Sujin	Sujin-H	ko-KR	Korean
Mijin	Female	Mijin	-	ko-KR	Korean
Maru	child	Maru	Maru-H	ko-KR	Korean
Hyejin	Female	Hyejin	Hyejin-H	ko-KR	Korean
Chris	Female	Chris	-	en-US	English (USA)
Richard	Male	Richard	Richard-H	en-US	English (USA)
Judy	Female	Judy	-	en-US	English (USA)
Sarah	Female	Sarah	Sarah-H	en-US	English (USA)
Xiaoling	Female	Xiaoling	Xiaoling-H	zh-CN	Chinese (Mandarin)
Jiaoling	Male	Jiaoling	Jiaoling-H	zh-CN	Chinese (Mandarin)
Naomi	Female	Naomi	-	ja-JP	Japanese
Eita	Male	Eita	Eita-H	ja-JP	Japanese
Otoha	Female	Otoha	Otoha-H	ja-JP	Japanese
Veronica	Female	Veronica	-	es-MX	Spanish (Mexico)
Claire	Female	Claire	-	en-GB	English (UK)
Monica	Female	Monica	-	pt-BR	Portuguese (Brazil)
Estelle	Female	Estelle	-	fr-CA	French (Canada)

6.3 Speechsynthesis

Application이 요청한 정보와 텍스트에 대하여 음성합성을 수행하고, 생성된 합성음을 반환합니다.

HTTP 요청 URI

POST /v2/tts/speechsynthesis

요청 예시

POST /v2/tts/speechsynthesis HTTP/1.1
Content-Type: application/json 
Authorization: Bearer ef2acb39-229d-42eb-bb13-1ef7d27f5c0b 
Host: cloud.selvy.ai
{
	"outputFormat": "pcm", 
	"sampleRate": "22050", 
	"text": "안녕하세요", 
	"textType": "text", 
	"voiceId": "Yujin" 
}

HTTP Header

Field Name	Mandatory	Example	Description
Content-Type	Y	application/json	-
Authorization	Y	Bearer ef2acb39-229d-42eb-bb13-1ef7d27f5c0b	- HTTP 인증을 위한 인증 자격증명에 사용됩니다. - Token Type(“Bearer”)과 함께 인증서버로부터 획득한 Access Token 을 입력합니다.

요청 Parameters

Name	Type	Mandatory	Default	Example	Notes
-	-	-	-	-	-

요청 Payloads

Node	Properties	Type	Mandatory	Description	Remarks
-	outputFormat	string	Y	결과 합성음의 오디오 포맷	- pcm, pcm_stream - wav - ogg - mp3, mp3_stream
-	sampleRate	string	N	결과 합성음의 오디오 주파수(단위 Hz)	- 22050 (기본 값) - 16000 - 8000
-	text	string	Y	음성합성 수행할 텍스트	-
-	textType	string	N	문자 데이터 포맷	- text (기본 값) - ssml
-	voiceId	string	Y	음성합성을 수행할 화자 아이디	- Voices API의 응답 Payloads의 id값을 동일하게 사용
-	speed	string	N	속도	기본값 -1, 범위 50~120
-	volume	string	N	음량	기본값 -1, 범위 0~200
-	pitch	string	N	음의 높이	기본값 -1, 범위 80~120

※ textType의 SSML은 ko-KR, en-US만 지원됩니다.

응답 예시

HTTP/1.1 200
Content-Type: audio/pcm Transfer-Encoding: chunked

<Audio Stream Binary>

응답 Header

Field Name	Mandatory	Example	Description
Content-Type	Y	pcm, pcm_stream : audio/pcm mp3, mp3_stream : audio/mpeg wav : audio/wav ogg : audio/ogg	output format 에 따라서 달라집니다.

응답 Payloads

Node	Properties	Type	Mandatory	Description
-	-	-	-	-

6.3.1 textType(SSML)

Tag	Attributes	Limitations/Restrictions
speak	version, xml:lang, xml:base	version is only 1.0
lexicon	uri	Follow PLS
p
s
say-as	interpret-as, format, detail	supported interpret-as value → date, time, telephone, characters, cardinal, ordinal
phoneme	alphabet, ph	supported alphabet value → ipa, x-sampa
sub	alias
voice	xml:lang, gender, name	supported gender value → male, female
emphasis	level
break	time, strength	supported scope of time value → 10ms ~ 10000ms(10s)
prosody	pitch, rate, volume
audio	src	supported src’s protocol → file://, http://
mark	name	<mark> tag is unavailable inside of a sentence.

※ SSML은 ko-KR, en-US만 지원됩니다.

7. 에러코드

7.1 에러코드의 구조

Name	Mandatory	Type	Example	Description
id	Y	string	400	오류 범위를 의미하는 코드
category	Y	string	tts	오류가 발생한 지점을 식별하기 위한 값
code	Y	string	1100	오류 유형을 의미하는 코드 (상세)
message	Y	string	요청 데이터 오류입니다.	발생한 오류에 대한 설명

7.2 에러코드의 설명

Http Status Code	ID	CODE	MESSAGE
200	200	200	정상
404	404	404	요청한 URI를 찾을 수 없습니다.
400	400	1100	요청 데이터 오류입니다.
		3002	사용 가능한 채널이 없습니다.
		3003	채널이 끊겼습니다.
		9401	필수 파라미터가 없습니다.

개발자 문서

1. Selvy CloudAPI 개요

2. Selvy CloudAPI 구성

3. 통신 방식

4. 호출 단계

5. 인증 방법 및 절차

5.1 인증 방법

5.2 인증 절차

Application(Client)

Auth Server(Service API)

Resource Server(Cloud Service Server)

5.3 Access Token

5.3.1 요청

HTTP 요청 URI

요청 Host 구성요소

요청 Parameters

5.3.2 응답

응답 Payloads - application/json

6. Selvy TTS API

6.1 Flow

6.2 Voices

HTTP 요청 URI

요청 예시

HTTP Header

요청 Parameters

요청 Payloads

응답 예시

응답 Header

응답 Payloads

6.2.1 Voice 지원현황

6.3 Speechsynthesis

HTTP 요청 URI

요청 예시

HTTP Header

요청 Parameters

요청 Payloads

응답 예시

응답 Header

응답 Payloads

6.3.1 textType(SSML)

7. 에러코드

7.1 에러코드의 구조

7.2 에러코드의 설명