연결 열기

WSS(WebSocket Secure) 프로토콜을 통해 /v1/synthesize 메소드를 호출하여 서비스에 대한 연결을 엽니다. 메소드는 다음 엔드포인트에서 사용 가능합니다.

wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}/v1/synthesize

여기서 {location}은 애플리케이션의 호스팅 위치를 나타냅니다.

• us-south는 댈러스
• us-east는 워싱턴 DC
• eu-de는 프랑크푸르트
• au-syd는 시드니
• jp-tok는 도쿄
• eu-gb는 런던
• kr-seo는 서울

{instance_id}는 서비스 인스턴스의 고유 ID입니다.

이 문서에 있는 예에서는 wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}을(를) {ws_url}(으)로 축약합니다. 그러므로 모든 WebSocket 예는 메소드를 {ws_url}/v1/synthesize로 호출합니다.

WebSocket 클라이언트는 다음 조회 매개변수와 함께 /v1/synthesize 메소드를 호출하여 서비스와의 인증된 연결을 설정합니다.

access_token(필수 문자열)

유효한 액세스 토큰을 전달하여 서비스에 인증하십시오. 액세스 토큰이 만료되기 전에 사용해야 합니다.

• IBM Cloud Identity and Access Management (IAM) 액세스 토큰을 전달하여 서비스에 인증합니다. 호출 시 API 키를 전달하는 대신 IAM 액세스 토큰을 전달합니다. 자세한 정보는 IBM Cloud에 대한 인증을 참조하십시오.
• IBM Cloud Pak for Data 노즈비 IBM Software Hub Authorization HTTP 요청의 액세스 토큰 헤더를 전달하는 것처럼 액세스 토큰을 전달합니다. 자세한 정보는 IBM Cloud Pak for Data 인증하기를 참고하세요.

voice(선택적 문자열)

텍스트가 오디오에서 음성화될 음성을 지정합니다. /v1/voices 메소드를 사용하여 지원되는 음성의 현재 목록을 가져오십시오. 기본 음성을 사용하도록 매개변수를 생략하십시오. 자세한 내용은 언어 및 음성 및 기본 음성 사용하기를 참조하세요.

customization_id(선택적 문자열)

합성에 사용할 사용자 정의 모델의 GUID(Globally Unique Identifier)를 지정합니다. 지정된 사용자 정의 모델은 합성에 사용되는 음성의 언어와 일치해야 합니다. 사용자 정의 ID를 포함하는 경우 사용자 정의 모델을 소유하는 서비스 인스턴스의 인증 정보를 사용하여 요청해야 합니다. 사용자 정의가 없는 지정된 음성을 사용하려면 매개변수를 생략하십시오. 자세한 정보는 사용자 정의 이해를 참조하십시오.

rate_percentage (선택 사항 integer)

전체 합성 요청에 대한 글로벌 말하기 속도를 지정합니다. 말하기 속도는 서비스가 합성한 텍스트를 음성으로 말하는 속도입니다. 속도가 높을수록 텍스트가 더 빨리 읽히고 속도가 낮을수록 텍스트가 더 느리게 읽힙니다. 이 매개변수는 전체 요청에 대한 음성당 기본 요금을 변경합니다. 자세한 내용은 말하기 속도 수정하기를 참조하세요.

pitch_percentage (선택 사항 integer)

전체 합성 요청에 대한 글로벌 말하기 피치를 지정합니다. 말하기 음조는 서비스에서 합성하는 음성의 톤을 나타냅니다. 청취자가 음성의 톤을 얼마나 높거나 낮게 인식하는지를 나타냅니다. 음높이가 높으면 높은 톤으로 말하고, 음높이가 낮으면 낮은 톤으로 말하게 됩니다. 이 매개변수는 전체 요청에 대한 음성별 기본 피치를 변경합니다. 자세한 내용은 말하기 음조 수정을 참조하세요.

spell_out_mode(선택적 문자열)

독일어 음성의 경우 문자열의 개별 문자를 어떻게 철자할지 지정합니다. 기본적으로 이 서비스는 언어의 텍스트를 합성하는 속도와 동일한 속도로 개별 문자를 철자합니다. 이 매개변수를 사용하여 서비스가 개별 문자의 철자를 1 singles, 2 pairs 또는 3 triples 그룹으로 더 느리게 철자하도록 지시할 수 있습니다. 자세한 내용은 문자열 철자법 지정하기를 참조하세요.

x-watson-metadata(선택적 문자열)

고객 ID를 연결을 통해 전달되는 데이터와 연관시킵니다. 매개변수는 customer_id={id} 인수를 허용합니다. 여기서, id는 무작위 문자열이거나 데이터와 연관되는 일반 문자열입니다. 매개변수에 대한 인수를 URL 인코딩해야 합니다(예: customer_id%3dmy_customer_ID). 기본적으로 고객 ID가 데이터와 연관되지 않습니다. 자세한 정보는 정보 보안을 참조하십시오.

x-watson-learning-opt-out(*선택적 * 부울)

IBM Cloud 서비스가 연결을 통해 전송되는 요청과 결과를 기록하는지 여부를 나타냅니다. IBM에서 일반적인 서비스 개선을 위해 데이터에 액세스하지 못하게 하려면 이 매개변수를 true로 지정하십시오. 옵트 아웃은 IBM이 요청에 대해 사용자 데이터(텍스트 또는 오디오)를 디스크에 쓰지 않도록 지시합니다. 계정 수준에서 옵트아웃할 수도 있습니다. 자세한 정보는 요청 로깅을 참조하십시오.

다음 JavaScript 코드의 스니펫을 통해 서비스와의 연결이 열립니다. /v1/synthesize 메소드에 대한 호출이 voice 조회 매개변수와 미국 영어 Allison 음성을 사용하도록 서비스에게 지시하는 access_token 조회 매개변수를 전달합니다. 연결이 설정되면 이벤트 리스너(onOpen(), onClose() 등)가 서비스의 이벤트에 응답하도록 정의됩니다.

var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/synthesize'
  + '?access_token=' + access_token
  + '&voice=en-US_AllisonV3Voice';
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };
websocket.onclose = function(evt) { onClose(evt) };
websocket.onmessage = function(evt) { onMessage(evt) };
websocket.onerror = function(evt) { onError(evt) };

입렉 텍스트 전송

텍스트를 합성하기 위해 클라이언트는 다음 매개변수를 사용하여 간단한 JSON 텍스트 메시지를 서비스에 전달합니다.

text(필수 문자열)

합성될 텍스트를 제공합니다. 클라이언트는 일반 텍스트 또는 SSML(Speech Synthesis Markup Language)로 어노테이션을 작성하는 텍스트를 전달할 수 있습니다. 클라이언트는 요청에 따라 최대 5KB의 입력 텍스트를 전달할 수 있습니다. 제한에는 지정하는 SSML이 포함됩니다. 자세한 정보는 입력 텍스트 지정 및 다음 절을 참조하십시오. (SSML 입력에는 <mark> 요소도 포함될 수 있습니다. 자세한 정보는 SSML 표시 지정을 참조하십시오.

accept(필수 문자열)

오디오의 요청된 형식(MIME 유형)을 지정합니다. */*를 사용하여 기본 오디오 형식인 audio/ogg;codecs=opus를 요청하십시오. 자세한 정보는 오디오 형식 사용을 참조하십시오.

Ogg 오디오 형식은 Safari 브라우저에서 지원되지 않습니다. Safari 브라우저에서 Text to Speech 서비스를 사용하는 경우에는 서비스에서 오디오를 반환할 다른 형식을 지정해야 합니다.

timings(선택적 문자열[ ])

서비스가 입력 텍스트의 모든 문자열에 대한 단어 시간 지정을 리턴하도록 지정합니다. 서비스는 입력에 대한 각 토큰의 시작 시간 및 종료 시간을 리턴합니다. 단어 시간 지정을 요청하기 위해 배열의 단독 요소로 words를 지정합니다. 비어 있는 배열을 지정하거나 매개변수를 생략하여 단어 시간 지정을 수신하지 않습니다. 자세한 내용은 단어 타이밍 생성을 참조하세요. 일본어 입력 텍스트에는 지원되지 않습니다.

다음 JavaScript 코드의 스니펫은 입력 텍스트로 단순 "Hello world" 메시지를 전달하고 오디오에 대한 기본 형식을 요청합니다. 호출은 연결이 설정된 후에만 전송되도록 하기 위해 클라이언트에 대해 정의된 onOpen() 함수에 포함됩니다.

function onOpen(evt) {
  var message = {
    text: 'Hello world',
    accept: '*/*'
  };
  websocket.send(JSON.stringify(message));
}

서비스는 오디오 응답의 형식을 확인하는 텍스트 메시지를 전송하여 이 메시지에 응답합니다. 다음 응답은 기본 오디오 형식을 확인합니다.

{
  'binary_streams': [
    {
      content_type: 'audio/ogg;codecs=opus'
    }
  ]
}

응답 수신

오디오 형식을 확인한 후 서비스는 표시된 형식을 사용하여 데이터의 바이너리 스트림으로 합성된 오디오를 전송합니다. 헤더(예: audio/wav 및 audio/ogg)가 포함된 오디오 형식의 경우 서비스는 오디오 데이터를 전송하기 전에 헤더를 리턴합니다. 헤더는 여러 바이너리 응답에 걸쳐 있을 수 있습니다. 모든 오디오 형식의 경우 완전한 오디오 응답을 어셈블하도록 서비스에서 모든 바이너리 응답을 추가해야 합니다.

요청된 오디오 형식을 확인하는 텍스트 메시지를 전송하는 것 외에도 서비스는 경고 또는 오류와 함께 텍스트 메시지를 전송할 수 있습니다. 다음과 같은 경우 서비스는 시간 지정 정보가 포함된 하나 이상의 텍스트 메시지도 전송합니다.

• 입력 텍스트에는 하나 이상의 SSML <mark> 요소가 포함됩니다.
• 요청에 따라 timings 매개변수를 지정합니다.

클라이언트는 오디오 결과에 응답하고, 오디오 결과를 표시하고, 애플리케이션의 사용을 위해 오디오 결과를 캡처하여 텍스트 메시지를 처리할 수 있습니다(예를 들어, 오디오 결과에 표시 위치가 포함된 경우).

입력 텍스트 합성과 모든 바이너리 및 텍스트 메시지 전송이 완료되면 서비스는 자동으로 WebSocket 연결을 닫습니다. 다음 간단한 onMessage() 함수는 서비스에서 수신되는 텍스트 및 2진 메시지를 유형에 따라 적절한 변수에 추가합니다. onClose() 함수가 실행되면 전체 오디오 스트림이 수신되고 서비스는 추가 바이너리 또는 텍스트 메시지를 전송하지 않습니다.

var messages;
var audioStream;

function onMessage(evt) {
  if (typeof evt.data === string) {
    messages += evt.data;
  } else {
    console.log('Received ' + evt.data.size() + ' binary bytes');
    audioStream += evt.data;
  }
}

function onClose(evt) {
  // The service's response is complete.
}

WebSocket 리턴 코드

서비스는 WebSocket 연결을 통해 리턴 코드를 클라이언트에 전송할 수 있습니다.

• 1000은 정상적인 연결의 닫기를 표시하며, 연결이 설정된 목적이 충족되었음을 의미합니다.
• 1002는 서비스는 프로토콜 오류로 인해 연결을 닫는 중임을 표시합니다.
• 1006은 연결이 비정상적으로 닫혔음을 표시합니다.
• 1009는 프레임 크기가 4MB 한계를 초과했음을 표시합니다.
• 1011은 서비스가 요청을 수행할 수 없는 예기치 않은 조건(예: 올바르지 않은 인수)이 발생했으므로 연결을 종료하는 중임을 표시합니다. 리턴 코드는 입력 텍스트가 너무 길었음을 표시할 수도 있습니다.

소켓이 오류와 함께 종료되는 경우 서비스는 닫기 전에 클라이언트에게 {"error": "Specific error message"} 형식의 정보 메시지를 전송합니다. 서비스는 알 수 없는 매개변수에 대해 치명적이지 않은 경고 메시지를 전송할 수도 있습니다. WebSocket 의 반환 코드에 대한 자세한 정보는 인터넷 엔지니어링 태스크 포스(IETF)의 RFC 6455를 참조하십시오.

SDK의 WebSocket 구현은 다르거나 더 많은 응답 코드를 리턴할 수 있습니다.

{
  "warnings": "Unknown arguments: invalid-parameter."
}