개발자 문서

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

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

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

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

    Cloud Service 명 설명
    Selvy TTS (음성합성 서비스) 문자로 받아들인 내용을 음성으로 변환시켜주는 서비스입니다.
  • Selvy CloudAPI는 HTTP를 이용하여 통신합니다. 세부 지원항목은 아래와 같습니다.

    항목 설명
    Method HTTP Method 중 정보를 가져오는 “GET”과 입력하는 “POST”를 사용하며, W3C에서 정한 규격을 따르고 있습니다.
    Header 요청에 대해 설명하는 메타정보를 포함합니다. 인증 Token을 전달하거나 응답 받을 컨텐츠 유형을 지정할 수 있습니다.
    Status Code HTTP 요청에 대한 결과를 나타내는 코드로, 잘못 요청 하였을 경우 400 Bad Request, 서버에 오류가 있을 경우 500을 반환합니다.
  • Selvy CloudAPI를 사용하기 위하여 먼저 인증 절차를 수행하여야 하며, 인증시 전달받은 Access Token을 이용하여 API 요청/응답 단계를 수행하여야 서비스를 정상적으로 이용할 수 있습니다.

    Step1. 인증 Step2. API 요청/응답

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

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

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

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

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

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

    접근권한은 표준화된 인증방식인 OAuth2.0를 이용하고 있습니다. 적용된 OAuth2.0의 인증방식은 Client Credentials Flow를 사용하여, Client가 적합한지 여부만 판단합니다.

  • 인증 flow - OAuth2.0 Client Credentials
    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)를 수행합니다.

  • 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
    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의 서비스 정책으로 정의되며, 정확한 명칭의 의미는 운영자를 통하여 전달
  • Selvy TTS(음성합성) API 사용을 위한 상세 개발 안내입니다.

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

    Step1. Voices Step2. Audiomix Step3. Userdic Step4. Speech synthesis Step5. MarkInfo

    Application이 요청한 언어에 대하여 사용 가능한 화자정보를 생성하여 반환

    Application이 음성합성시 배경음으로 사용할 파일을 등록

    Application이 음성합성시 사용자사전으로 사용할 텍스트를 등록

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

    생성된 합성음에 대한 Markup정보(Highlight, Lipsync)를 반환

  • 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
    Basic High-Quality
    USS
    High-Quality
    DNN
    YujinFemaleYujinYujin-HYujin-H-DNNko-KRKorean
    MinjunMaleMinjunMinjun-HMinjun-H-DNNko-KRKorean
    AramchildAramAram-HAram-H-DNNko-KRKorean
    GichanMaleGichanGichan-HGichan-H-DNNko-KRKorean
    SujinFemaleSujinSujin-HSujin-H-DNNko-KRKorean
    MijinFemaleMijinMijin-HMijin-H-DNNko-KRKorean
    MaruchildMaruMaru-HMaru-H-DNNko-KRKorean
    SantaMale--Santa-H-DNNko-KRKorean
    HyejinFemaleHyejinHyejin-HHyejin-H-DNNko-KRKorean
    HanaFemale--Hana-H-DNNko-KRKorean
    ChrisFemaleChris--en-USEnglish (USA)
    RichardMaleRichardRichard-H-en-USEnglish (USA)
    JudyFemaleJudy--en-USEnglish (USA)
    SarahFemaleSarahSarah-H-en-USEnglish (USA)
    XiaolingFemaleXiaolingXiaoling-H-zh-CNChinese (Mandarin)
    JiaolingMaleJiaolingJiaoling-H-zh-CNChinese (Mandarin)
    NaomiFemaleNaomi--ja-JPJapanese
    EitaMaleEitaEita-H-ja-JPJapanese
    OtohaFemaleOtohaOtoha-H-ja-JPJapanese
    VeronicaFemaleVeronica--es-MXSpanish (Mexico)
    ClaireFemaleClaire--en-GBEnglish (UK)
    MonicaFemaleMonica--pt-BRPortuguese (Brazil)
    EstelleFemaleEstelle--fr-CAFrench (Canada)
  • Application이 음성합성시 배경음으로 사용할 파일을 등록합니다.

    HTTP 요청 URI

    POST /v2/tts/audiomix

    요청 예시
    POST /v2/tts/audiomix HTTP/1.1
    Content-Type: multipart/form-data
    Authorization: Bearer ef2acb39-229d-42eb-bb13-1ef7d27f5c0b
    Host: cloud.selvy.ai
    
    Body:
    file : C:/audio/response.wav
    mixingId : m00001
    
    HTTP Header
    Field Name Mandatory Example Description
    Content-Type Y multipart/form-data -
    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
    - file MultipartFile Y - 배경음 wave 파일 확장자(wav), 파일크기(10M이내), 기타(Encoding, Mono, 16bit linear pcm 만 지원) -
    - mixingId string Y 고객에서 관리하는 배경음ID 5~10자 (영어 대·소문자, 숫자만 가능) -
    응답 예시
    {
        "code": "200",
        "message": "Success"
    }
    
    응답 Header
    Field Name Mandatory Example Description
    - - - -
    응답 Payloads
    Node Properties Type Mandatory Description
    - - - - -
  • Application이 음성합성시 사용자사전으로 사용할 텍스트를 등록합니다.

    HTTP 요청 URI

    POST /v2/tts/userdic

    요청 예시
    POST /v2/tts/userdic HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer ef2acb39-229d-42eb-bb13-1ef7d27f5c0b
    Host: cloud.selvy.ai
    
    Body:
    {
        "lang": "ko-KR",
        "userDicId": "332321kr",
        "userDicText": "{38선} {삼팔선}\n{63빌딩} {육삼빌딩}\n{^^} {킥킥}"
    }
    
    {
        "lang": "zh-CN",
        "userDicId": "332321cn",
        "userDicText": "[W*TEXT] 莲池公园\n[W*READ] yan1ji1gong1wen1\n[W*TEXT] NO.1\n[W*READ] di4yi1"
    }
    
    {
        "lang": "en-GB",
        "userDicId": "332321gb",
        "userDicText": "[W*TEXT] SELVAS AI\n[W*READ] [\"sElv@s] [\"e\"aI]\n[W*TEXT] TTS\n[W*READ] [t \"i t j e s] "
    }
    
    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
    - lang string Y - 지정한 언어 코드
    6.2.1 Voice 지원현황 참고
    -
    - userDicId string Y 고객에서 관리하는 사용자사전 ID
    5~10자 (영어 대·소문자, 숫자만 가능)
    -
    - userDicText string Y [한국어]
    {Entry Original} {Entry Read}

    [한국어를 제외한 모든 언어]
    [W-TEXT] km
    [W-READ] kilometer

    개행은 \n으로 표기
    큰따옴표(double quotation mark) 앞에는 \을 붙임
    -
    응답 예시
    {
        "code": "200",
        "message": "Success"
    }
    
    응답 Header
    Field Name Mandatory Example Description
    - - - -
    응답 Payloads
    Node Properties Type Mandatory Description
    - - - - -
  • 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
    - markInfo string N Highlight와 Lipsync 생성여부 기본값 N
    생성 : Y, 미생성 : N or 빈값
    - userDicId string N 사용자사전 ID 고객에서 관리하는 사용자사전 ID / 5~10자 (영어 대·소문자, 숫자만 가능)
    - mixingId string N 배경음 ID 고객에서 관리하는 배경음ID / 5~10자 (영어 대·소문자, 숫자만 가능)

    ※ 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 에 따라서 달라집니다.
    markInfoKey N - markInfo를 'Y'로 전달 시 생성 됩니다.
    응답 Payloads
    Node Properties Type Mandatory Description
    - - - - -

    6.5.1 textType(SSML)

    Tag Attributes Limitations/Restrictions
    speakversion, xml:lang, xml:baseversion is only 1.0
    lexiconuriFollow PLS
    p
    s
    say-asinterpret-as, format, detailsupported interpret-as value
    → date, time, telephone, characters, cardinal, ordinal
    phonemealphabet, phsupported alphabet value
    → ipa, x-sampa
    subalias
    voicexml:lang, gender, namesupported gender value
    → male, female
    emphasislevel
    breaktime, strengthsupported scope of time value
    → 10ms ~ 10000ms(10s)
    prosodypitch, rate, volume
    audiosrcsupported src’s protocol
    → file://, http://
    markname<mark> tag is unavailable inside of a sentence.

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

  • 생성된 합성음에 대한 Markup정보(Highlight, Lipsync)를 반환합니다.

    HTTP 요청 URI

    POST /v2/tts/markInfo

    요청 예시
    POST /v2/tts/markInfo HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer ef2acb39-229d-42eb-bb13-1ef7d27f5c0b
    Host: cloud.selvy.ai
    
    Body:
    {
    "markInfoKey": "dk12EW4832Rt"
    }
    
    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
    - markInfoKey string Y speechsynthesis의 응답 Header로 전달 받은 markInfoKey(영어 대·소문자, 숫자 12자리) -
    응답 예시
    {
        "highlight": "0\t10\t932\r\n12\t29\t2099\r\n31\t47\t1784",
        "lipsync": "5\t51\t0\t0\t0\t50\t0\r\n3\t21\t42\t0\t50\t147\t21674\r\n1\t3\t26\t47\t197\t130\t6968\r\n4\t21\t0\t0\t327\t87\t9186\r\n2\t10\t22\t0\t415\t160\t6351\r\n
    4\t26\t0\t0\t575\t306\t6768\r\n5\t51\t0\t0\t882\t50\t0\r\n5\t51\t0\t0\t932\t550\t0\r\n1\t7\t21\t42\t1482\t195\t15843\r\n2\t3\t21\t0\t1678\t147\t10518",
        "markInfoKey": "dk12EW4832Rt",
        "code": "200",
        "message": "Success"
    }
    
    응답 Header
    Field Name Mandatory Example Description
    - - - -
    응답 Payloads
    Node Properties Type Mandatory Description
    - Highlight string N 하이라이트 정보
    - Lipsync string N 립싱크 정보
    - markInfoKey string N markInfo 키값
    - code string Y 코드
    - message string Y 메시지
  • Name Mandatory Type Example Description
    id Y string 400 오류 범위를 의미하는 코드
    category Y string tts 오류가 발생한 지점을 식별하기 위한 값
    code Y string 1100 오류 유형을 의미하는 코드 (상세)
    message Y string 요청 데이터 오류입니다. 발생한 오류에 대한 설명
  • Http Status Code ID CODE MESSAGE
    200 200 200 정상
    404 404 404 요청한 URI를 찾을 수 없습니다.
    400 400 1100 요청 데이터 오류입니다.
    3002 사용 가능한 채널이 없습니다.
    3003 채널이 끊겼습니다.
    9401 필수 파라미터가 없습니다.