ROS 2 Humble이 설치된 TurtleBot3 Burger에서 Google Cloud Text-to-Speech API를 사용하려면 먼저 Google Cloud 프로젝트, 결제 계정, API, 서비스 계정, 인증 키를 설정해야 합니다.
이번 설정의 최종 목표는 다음과 같습니다.
Google Cloud 프로젝트 생성
→ 결제 계정 연결
→ Cloud Text-to-Speech API 활성화
→ 서비스 계정 생성
→ 최소 권한 설정
→ JSON 인증 키 발급
→ TurtleBot3에 인증 키 설치
이 글에서는 Python 코드에서 다음 방식으로 인증하는 것을 기준으로 설명합니다.
from google.cloud import texttospeech
client = texttospeech.TextToSpeechClient()
TextToSpeechClient()는 Application Default Credentials, ADC 방식을 사용하여 인증 정보를 자동으로 찾습니다. TurtleBot3에서는 서비스 계정 JSON 키 파일의 위치를 GOOGLE_APPLICATION_CREDENTIALS 환경변수로 지정합니다. Google Cloud 클라이언트 라이브러리는 해당 환경변수를 ADC 인증 정보 검색 위치로 우선 확인합니다.
1. 먼저 알아야 할 인증 방식
Google Cloud Text-to-Speech를 사용하면서 가장 혼동하기 쉬운 부분은 API 키, OAuth 클라이언트, 서비스 계정의 차이입니다.
이번 TurtleBot3 프로젝트에서 사용할 것은 서비스 계정입니다.
API 키
사용하지 않음
OAuth 클라이언트 ID
사용하지 않음
서비스 계정
사용함
서비스 계정 JSON 키
TurtleBot3에서 ADC 인증에 사용
Google Cloud Console의 API 및 서비스 → 사용자 인증 정보 화면에는 여러 종류의 인증 정보를 만들 수 있지만, 이번 ROS 2 프로그램에서는 일반 API 키를 생성할 필요가 없습니다.
Google Cloud Python 클라이언트 라이브러리가 서비스 계정의 JSON 인증 파일을 읽고 액세스 토큰을 자동으로 생성하기 때문입니다.
서비스 계정 JSON 키 방식은 설정이 간단하여 개인용 로봇이나 실습 프로젝트에 적합합니다. 다만 Google은 Google Cloud 외부에서 실행되는 운영 시스템에는 서비스 계정 키보다 Workload Identity Federation 사용을 권장합니다. 서비스 계정 키는 유출되면 추가 인증 없이 악용될 수 있으므로 직접 보안을 관리해야 합니다.
TurtleBot3 한 대를 사용하는 개인 개발 환경에서는 JSON 키 방식이 가장 현실적입니다. 여러 대의 로봇을 상용 서비스로 운영한다면 Workload Identity Federation이나 별도의 인증 프록시 서버 구조를 검토하는 것이 좋습니다.
2. Google Cloud Console 접속
Google 계정으로 Google Cloud Console에 로그인합니다.
처음 Google Cloud를 사용하는 경우 약관 동의와 결제 프로필 설정이 표시될 수 있습니다.
Google Cloud Console 상단에는 현재 선택된 프로젝트가 표시됩니다. 앞으로 프로젝트, 결제, API, IAM 설정을 변경하기 전에 항상 올바른 프로젝트가 선택되어 있는지 확인해야 합니다.
My First Project를 선택하고 새 프로젝트를 클릭합니다.
예를 들어 프로젝트 이름을 다음과 같이 구성할 수 있습니다.
프로젝트 이름: HuRo TTS
프로젝트 ID: huro-tts-202608
프로젝트 이름은 화면에 표시되는 이름이고 프로젝트 ID는 API, 명령어, 서비스 계정 주소에서 사용되는 고유 식별자입니다.
서비스 계정 이메일은 다음과 같은 형식으로 생성됩니다.
huro-tts@huro-tts-202608.iam.gserviceaccount.com
3. Google Cloud 프로젝트 생성
Google Cloud Console 상단의 프로젝트 선택 영역을 클릭합니다.
다음 순서로 진행합니다.
상단 프로젝트 선택
→ 새 프로젝트
→ 프로젝트 이름 입력
→ 프로젝트 ID 확인
→ 조직 및 위치 확인
→ 만들기
1) 프로젝트 이름 입력
프로젝트 이름은 관리자가 알아보기 쉬운 이름으로 설정합니다.
HutRo TTS
프로젝트 이름은 나중에 변경할 수 있으므로 너무 복잡하게 만들 필요는 없습니다.
2) 프로젝트 ID 확인
프로젝트 ID는 Google Cloud API와 명령행에서 자주 사용되므로 짧고 명확하게 설정하는 것이 좋습니다.
예시는 다음과 같습니다.
huro-tts-202608
프로젝트 ID에는 일반적으로 소문자, 숫자, 하이픈을 사용합니다.
이후 명령어에서 다음 값을 사용하게 됩니다.
PROJECT_ID="huro-tts-202608"
3) 조직과 위치 선택
개인 Google 계정을 사용하면 조직이 표시되지 않거나 조직 없음으로 표시될 수 있습니다.
회사나 학교의 Google Workspace 계정을 사용하면 조직과 폴더를 선택해야 할 수 있습니다. 이 경우 조직 관리자가 서비스 계정 키 생성이나 결제 연결을 제한했을 가능성이 있습니다.
모든 값을 확인한 다음 만들기를 누릅니다.
프로젝트가 생성되면 상단 프로젝트 선택 메뉴에서 방금 생성한 프로젝트를 선택합니다. Google Cloud 공식 절차도 프로젝트 선택기에서 기존 프로젝트를 선택하거나 새 프로젝트를 생성한 뒤 결제를 연결하고 API를 활성화하는 순서로 안내합니다.
4. 결제 계정 연결
Cloud Text-to-Speech API를 사용하려면 프로젝트에 활성 상태의 Cloud Billing 계정이 연결되어 있어야 합니다.
무료 사용량 안에서 사용하더라도 결제 계정 연결 자체는 필요합니다. Google 공식 문서에서도 Cloud Text-to-Speech API 사용을 위해 결제 활성화를 요구하며, 무료 할당량을 초과하지 않으면 해당 범위에서는 과금되지 않는다고 안내합니다.
Google Cloud Console 왼쪽 메뉴에서 다음 순서로 이동합니다.
결제
→ 결제 계정 연결
영문 화면에서는 다음과 같이 표시됩니다.
Billing
→ Link a billing account
1) 기존 결제 계정이 있는 경우
사용 가능한 결제 계정 목록에서 사용할 계정을 선택하고 프로젝트에 연결합니다.
프로젝트와 결제 계정 연결 상태는 다음 메뉴에서 확인할 수 있습니다.
결제
→ 내 프로젝트
프로젝트 행의 결제 계정 열에 연결된 계정 이름이 표시되면 정상입니다.
2) 결제 계정이 없는 경우
새 결제 계정을 생성합니다.
일반적으로 다음 정보가 필요합니다.
국가
계정 유형
이름 또는 사업자 정보
주소
결제 카드
세금 정보
국가와 결제 프로필 유형은 이후 변경하기 어려울 수 있으므로 정확하게 선택해야 합니다.
결제 계정 생성이 완료되면 방금 만든 TurtleBot3 프로젝트에 해당 결제 계정을 연결합니다.
Google Cloud 프로젝트의 결제는 활성 상태의 Cloud Billing 계정과 연결되어 있을 때 활성화됩니다. 기존 프로젝트에서 결제를 연결하려면 결제 → 내 프로젝트에서 프로젝트의 작업 메뉴를 열고 결제 변경을 선택할 수 있습니다.
3) 결제 연결 상태 확인
내 결제 계정 -> 결제 계정 관리를 클릭합니다.
다음 항목을 확인합니다.
프로젝트: huro-tts-202608
결제 계정: 연결됨
결제 계정 상태: 활성
결제 계정이 정지되거나 프로젝트와 연결이 해제되면 Cloud Text-to-Speech API 요청이 실패할 수 있습니다.
5. 예산 알림 설정
왼쪽 메뉴에서 예산 및 알림 메뉴를 선택합니다.
결제 계정을 연결한 직후 예산 알림을 설정하는 것이 좋습니다.
Google Cloud Console에서 다음 순서로 이동합니다.
결제
→ 비용 관리
→ 예산 및 알림
→ 예산 만들기
영문 화면에서는 다음과 같습니다.
Billing
→ Cost management
→ Budgets & alerts
→ Create budget
1) 예산 이름
다음과 같이 입력합니다.
HuRo TTS Monthly Budget
2) 예산 범위
전체 결제 계정이 아니라 TurtleBot3 프로젝트만 선택합니다.
프로젝트:
huro-tts-202608
서비스 필터를 지원하는 화면이라면 Cloud Text-to-Speech 서비스만 선택할 수 있습니다.
3) 예산 금액
개인 실습 프로젝트라면 소액으로 설정합니다.
예시는 다음과 같습니다.
월 예산: 10,000원
또는 달러 기준으로 표시된다면 다음과 같이 설정할 수 있습니다.
월 예산: 10 USD
4) 알림 기준
다음과 같이 여러 단계로 설정합니다.
50% 도달
90% 도달
100% 도달
예산 알림 이메일 수신 설정도 활성화합니다.
중요한 점은 예산 알림이 비용 발생을 자동으로 차단하지는 않는다는 것입니다. 설정한 금액을 초과하면 이메일을 보내지만 API가 자동으로 중지되는 하드 한도는 아닙니다. 따라서 ROS 2 노드에서도 요청 빈도 제한, 중복 문자열 제거, 최대 문자열 길이 제한을 구현해야 합니다.
6. Cloud Text-to-Speech API 활성화
현재 선택된 프로젝트가 TurtleBot3 프로젝트인지 확인합니다.
현재 프로젝트:
HuRo Text to Speech
Google Cloud Console 상단 검색창에 다음을 입력합니다.
Cloud Text-to-Speech API
검색 결과에서 정확히 다음 서비스를 선택합니다.
Cloud Text-to-Speech API
다음 서비스와 혼동하면 안 됩니다.
Cloud Speech-to-Text API
Vertex AI API
Dialogflow API
Cloud Translation API
Cloud Text-to-Speech API 페이지에서 사용 버튼을 클릭합니다.
영문 화면에서는 Enable 버튼입니다.
Cloud Text-to-Speech API
→ 사용
Google Cloud 공식 문서에서도 프로젝트와 결제 계정을 준비한 뒤 상단 검색창에서 speech를 검색하고 Cloud Text-to-Speech API를 선택하여 활성화하도록 안내합니다.
1) API 활성화 상태 확인
API가 정상적으로 활성화되면 버튼이 사용에서 관리로 변경됩니다.
다음 메뉴에서도 확인할 수 있습니다.
API 및 서비스
→ 사용 설정된 API 및 서비스
목록에서 다음 항목을 찾습니다.
Cloud Text-to-Speech API
서비스 이름은 다음과 같습니다.
texttospeech.googleapis.com
Cloud Shell이나 Google Cloud CLI를 사용할 수 있다면 다음 명령으로도 확인할 수 있습니다.
gcloud services list \
--enabled \
--filter="name:texttospeech.googleapis.com"
API가 활성화되지 않았다면 다음 명령으로 활성화할 수 있습니다.
gcloud services enable texttospeech.googleapis.com \
--project="huro-tts-202608"
API를 활성화하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트 소유자는 일반적으로 이 권한을 가지고 있으며, 다른 사용자가 설정하는 경우 Service Usage Admin 역할이 필요할 수 있습니다.
7. 서비스 계정 생성
서비스 계정은 TurtleBot3의 ROS 2 노드가 Google Cloud API를 호출할 때 사용하는 로봇용 계정입니다.
개인 Google 계정의 이메일과 비밀번호를 TurtleBot3에 저장하면 안 됩니다. 대신 로봇 전용 서비스 계정을 생성합니다.
Google Cloud Console에서 다음 순서로 이동합니다.
IAM 및 관리자
→ 서비스 계정
→ 서비스 계정 만들기
영문 화면에서는 다음과 같습니다.
IAM & Admin
→ Service Accounts
→ Create service account
1) 서비스 계정 이름
다음과 같이 입력합니다.
HuRo TTS
2) 서비스 계정 ID
다음과 같이 입력합니다.
huro-tts-202608
서비스 계정 이메일은 자동으로 만들어집니다.
huro-tts@huro-tts-202608.iam.gserviceaccount.com
서비스 계정 ID는 생성 후 변경할 수 없으므로 용도를 알 수 있도록 설정해야 합니다. Google Cloud는 서비스 계정 ID를 6자에서 30자 사이의 소문자, 숫자, 하이픈 형식으로 생성하며, 이 ID가 서비스 계정 이메일 주소에 포함됩니다.
3) 서비스 계정 설명
다음과 같이 작성합니다.
ROS 2 Humble HRo에서
Google Cloud Text-to-Speech API를 호출하기 위한 서비스 계정
만들고 계속하기를 선택합니다.
8. 서비스 계정 권한 설정
서비스 계정 권한 설정 화면에서 역할을 추가합니다.
검색창에 다음 역할을 입력합니다.
Service Usage Consumer
한국어 화면에서는 다음과 비슷하게 표시될 수 있습니다.
서비스 사용량 소비자
역할 식별자는 다음과 같습니다.
roles/serviceusage.serviceUsageConsumer
이 역할에는 프로젝트의 활성화된 서비스를 사용하고 소비 프로젝트의 할당량을 사용하는 데 필요한 serviceusage.services.use 권한이 포함됩니다. Google Cloud TTS 인증 문서에서도 사용자 또는 클라이언트가 이 권한이 없으면 일부 명령과 클라이언트 라이브러리가 동작하지 않을 수 있다고 안내합니다.
권한 설정은 다음과 같이 구성합니다.
서비스 계정:
huro-tts@huro-tts-202608.iam.gserviceaccount.com
역할:
Service Usage Consumer
다음과 같은 광범위한 역할은 추가하지 않는 것이 좋습니다.
Owner
Editor
Viewer
특히 Owner와 Editor는 TTS 음성 합성만 수행하는 로봇에 과도한 권한입니다. Google Cloud 공식 인증 문서도 운영 환경의 서비스 계정에 Owner, Editor, Viewer 같은 기본 역할을 부여하지 말고 필요한 사전 정의 역할 또는 사용자 정의 역할만 부여하도록 안내합니다.
기본적인 Text-to-Speech 음성 합성에서는 Cloud Storage, Compute Engine, BigQuery 등의 권한이 필요하지 않습니다.
권한 설정을 완료한 다음 완료를 누릅니다.
1) 권한을 나중에 추가하는 방법
서비스 계정을 먼저 만든 경우 다음 메뉴에서 권한을 추가할 수 있습니다.
IAM 및 관리자
→ IAM
→ 액세스 권한 부여
새 주 구성원에 서비스 계정 이메일을 입력합니다.
huro-tts@huro-tts-202608.iam.gserviceaccount.com
역할에 다음을 선택합니다.
Service Usage Consumer
Cloud Shell에서는 다음 명령을 사용할 수 있습니다.
PROJECT_ID="turtlebot3-tts-2026"
SERVICE_ACCOUNT_NAME="turtlebot3-tts"
gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
--member="serviceAccount:${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
--role="roles/serviceusage.serviceUsageConsumer"
9. 서비스 계정 JSON 키 생성
서비스 계정 목록에서 방금 만든 서비스 계정의 이메일을 클릭합니다.
huro-tts@huro-tts-202608.iam.gserviceaccount.com
상단 탭에서 다음 순서로 이동합니다.
키
→ 키 추가
→ 새 키 만들기
영문 화면에서는 다음과 같습니다.
Keys
→ Add key
→ Create new key
키 유형으로 JSON을 선택합니다.
키 유형: JSON
만들기를 누릅니다.
Google Cloud 공식 절차도 서비스 계정 이메일을 선택한 뒤 Keys → Add key → Create new key → JSON → Create 순서로 키를 생성하도록 안내합니다.
JSON 파일이 자동으로 다운로드됩니다.
파일 이름은 다음과 비슷합니다.
huro-tts-202608-2fd5a1ed8a6e.json
1) JSON 키는 한 번만 다운로드 가능
JSON 키는 생성 시 한 번만 다운로드됩니다.
다운로드한 파일을 잃어버렸다고 해서 같은 개인 키를 다시 다운로드할 수는 없습니다. 잃어버린 경우 기존 키를 삭제하고 새 키를 생성해야 합니다.
2) JSON 키 파일의 내용
JSON 키 파일은 대략 다음 정보를 포함합니다.
{
"type": "service_account",
"project_id": "huro-tts-202608",
"private_key_id": "키 식별자",
"private_key": "-----BEGIN PRIVATE KEY-----",
"client_email": "huro-tts@huro-tts-202608.iam.gserviceaccount.com",
"client_id": "112887394783570822217",
"token_uri": "https://oauth2.googleapis.com/token"
}
이 파일에서 가장 중요한 항목은 private_key입니다.
파일을 획득한 사람은 서비스 계정으로 인증할 수 있으므로 비밀번호보다 더 엄격하게 관리해야 합니다.
10. 새 키 만들기 버튼이 비활성화된 경우
회사나 학교 조직 계정에서는 키 추가 또는 새 키 만들기 버튼이 비활성화될 수 있습니다.
대표적인 원인은 다음 조직 정책입니다.
iam.disableServiceAccountKeyCreation
Google Cloud 조직이 2024년 5월 3일 이후 생성된 경우 해당 제약조건이 기본 적용될 수 있습니다. 정책이 적용되어 있으면 프로젝트에서 서비스 계정 JSON 키를 만들 수 없습니다.
이 경우 선택지는 다음과 같습니다.
- 조직 관리자에게 서비스 계정 키 생성 정책 확인 요청
- 개인 Google 계정으로 별도 프로젝트 생성
- Workload Identity Federation 구성
- Google Cloud에서 실행되는 중계 서버 사용
- 서비스 계정 가장 방식 사용
조직 정책을 무조건 해제하는 것은 권장하지 않습니다.
11. 다운로드한 JSON 키 보관
다운로드 폴더에 JSON 키를 그대로 두면 안 됩니다.
Google은 브라우저로 키를 생성한 경우 다운로드 폴더나 휴지통 등에 사본을 남기지 말고 즉시 안전한 위치로 이동하도록 권고합니다. 또한 가능한 경우 서비스 계정 키를 파일 시스템에 저장하지 않는 것이 좋으며, 저장해야 한다면 접근 권한을 제한하고 디스크 보안을 적용해야 합니다.
개발 PC에서 다음과 같이 별도 디렉터리를 만듭니다.
mkdir -p ~/.config/google-cloud-keys
chmod 700 ~/.config/google-cloud-keys
다운로드한 파일을 이동합니다.
mv ~/Downloads/huro-tts-202608-*.json \
~/.config/google-cloud-keys/huro-tts.json
파일 권한을 제한합니다.
chmod 600 ~/.config/google-cloud-keys/huro-tts.json
다음 위치에는 저장하면 안 됩니다.
~/ros2_ws/src/
Git 저장소
GitHub
공개 NAS
공유 폴더
Docker 이미지 내부
블로그 첨부 파일
메신저 대화방
Git 저장소의 .gitignore에는 다음 항목을 추가하는 것이 좋습니다.
*.json
*service-account*
*credentials*
google-cloud-keys/
단, .gitignore에 추가하기 전에 이미 Git에 커밋했다면 기록에 키가 남아 있을 수 있습니다. 이 경우 파일만 삭제하지 말고 Google Cloud Console에서 해당 키를 즉시 폐기한 후 새 키를 만들어야 합니다.
12. JSON 키를 TurtleBot3로 복사
TurtleBot3에 SSH로 접속할 수 있어야 합니다.
TurtleBot3의 사용자 이름을 ubuntu, IP 주소를 192.168.0.30이라고 가정합니다.
먼저 TurtleBot3에 인증 파일 디렉터리를 생성합니다.
ssh ubuntu@192.168.210.12
TurtleBot3에서 다음 명령을 실행합니다.
mkdir -p ~/.config/google-cloud-keys
chmod 700 ~/.config/google-cloud-keys
개발 PC 터미널에서 JSON 키를 복사합니다.
scp ~/.config/google-cloud-keys/huro-tts.json \
sjyong@192.168.210.12:/home/sjyong/.config/google-cloud-keys/huro-tts.json
TurtleBot3에서 파일 권한을 설정합니다.
chmod 600 ~/.config/google-cloud-keys/huro-tts.json
파일을 확인합니다.
ls -l ~/.config/google-cloud-keys/huro-tts.json
정상적인 권한은 다음과 비슷합니다.
-rw------- 1 ubuntu ubuntu ...
소유자만 읽고 쓸 수 있어야 합니다.
13. GOOGLE_APPLICATION_CREDENTIALS 설정
TurtleBot3에서 다음 환경변수를 설정합니다.
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/google-cloud-keys/huro-tts.json"
설정값을 확인합니다.
echo "$GOOGLE_APPLICATION_CREDENTIALS"
출력은 다음과 같습니다.
/home/ubuntu/.config/google-cloud-keys/huro-tts.json
파일 존재 여부도 확인합니다.
test -f "$GOOGLE_APPLICATION_CREDENTIALS" \
&& echo "인증 파일 확인 완료" || echo "인증 파일을 찾을 수 없음"
Google Cloud ADC는 먼저 GOOGLE_APPLICATION_CREDENTIALS 환경변수에 지정된 파일을 확인하고, 다음으로 gcloud auth application-default login으로 생성된 로컬 인증 파일, 마지막으로 Google Cloud 리소스에 연결된 서비스 계정을 확인합니다.
1) 로그인할 때 자동 적용
~/.bashrc에 환경변수를 추가합니다.
echo 'export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/google-cloud-keys/huro-tts.json"' >> ~/.bashrc
현재 터미널에 적용합니다.
source ~/.bashrc
다시 확인합니다.
echo "$GOOGLE_APPLICATION_CREDENTIALS"
환경변수는 기본적으로 설정한 셸 세션에만 적용되므로 새 터미널에서도 사용하려면 셸 설정 파일이나 실행 환경에 별도로 등록해야 합니다.
2) systemd 서비스로 실행하는 경우
ROS 2 노드를 systemd 서비스로 자동 실행한다면 .bashrc가 로드되지 않을 수 있습니다.
서비스 파일에 환경변수를 직접 지정합니다.
[Service]
Environment="GOOGLE_APPLICATION_CREDENTIALS=/home/ubuntu/.config/google-cloud-keys/turtlebot3-tts.json"
또는 환경 파일을 별도로 만듭니다.
sudo nano /etc/huro-tts.env
다음 내용을 입력합니다.
GOOGLE_APPLICATION_CREDENTIALS=/home/ubuntu/.config/google-cloud-keys/huro-tts.json
systemd 서비스에는 다음을 추가합니다.
[Service]
EnvironmentFile=/etc/huro-tts.env
환경 파일 권한도 제한합니다.
sudo chmod 600 /etc/huro-tts.env
14. 인증 파일 유효성 확인
JSON 형식이 정상인지 확인합니다.
python3 -m json.tool \
"$GOOGLE_APPLICATION_CREDENTIALS" \
> /dev/null
오류가 없다면 JSON 형식은 정상입니다.
프로젝트 ID를 확인합니다.
python3 - <<'PY'
import json
import os
path = os.environ["GOOGLE_APPLICATION_CREDENTIALS"]
with open(path, "r", encoding="utf-8") as file:
credentials = json.load(file)
print("type :", credentials.get("type"))
print("project_id :", credentials.get("project_id"))
print("email :", credentials.get("client_email"))
PY
정상 출력 예시는 다음과 같습니다.
type : service_account
project_id : turtlebot3-tts-2026
email : turtlebot3-tts@turtlebot3-tts-2026.iam.gserviceaccount.com
다음 조건을 확인합니다.
type이 service_account인지
project_id가 올바른 프로젝트인지
client_email이 만든 서비스 계정인지
개인 키 자체를 화면에 출력하면 안 됩니다.
cat "$GOOGLE_APPLICATION_CREDENTIALS"
위 명령은 JSON 내부의 개인 키까지 터미널에 표시하므로 사용하지 않는 것이 좋습니다.
15. Google Cloud Python 인증 테스트
Google Cloud Text-to-Speech 라이브러리를 설치합니다.
python3 -m pip install \
--user \
--upgrade \
google-cloud-texttospeech
다음 테스트 코드를 실행합니다.
python3 - <<'PY'
from google.cloud import texttospeech
client = texttospeech.TextToSpeechClient()
voices = client.list_voices(
language_code="ko-KR"
)
print("Google Cloud 인증 성공")
print("한국어 음성 수:", len(voices.voices))
for voice in voices.voices[:10]:
print(voice.name)
PY
인증과 API 설정이 정상이라면 다음과 비슷하게 출력됩니다.
Google Cloud 인증 성공
한국어 음성 수: ...
ko-KR-Standard-A
ko-KR-Standard-B
...
사용 가능한 음성은 서비스 업데이트에 따라 변경될 수 있으므로 코드에서 list_voices()를 호출하여 현재 프로젝트에서 사용할 수 있는 음성을 확인하는 것이 가장 정확합니다. Google Cloud는 voices.list API와 클라이언트 라이브러리 예제를 제공합니다.
16. 실제 음성 합성 테스트
다음 코드는 Google Cloud에서 한국어 음성을 생성하고 WAV 파일로 저장합니다.
python3 - <<'PY'
from google.cloud import texttospeech
client = texttospeech.TextToSpeechClient()
synthesis_input = texttospeech.SynthesisInput(
text="안녕하세요. 휴로 음성 출력 테스트입니다."
)
voice = texttospeech.VoiceSelectionParams(
language_code="ko-KR",
name="ko-KR-Standard-A",
)
audio_config = texttospeech.AudioConfig(
audio_encoding=texttospeech.AudioEncoding.LINEAR16
)
response = client.synthesize_speech(
input=synthesis_input,
voice=voice,
audio_config=audio_config,
)
output_path = "/tmp/huro_tts_test.wav"
with open(output_path, "wb") as file:
file.write(response.audio_content)
print("음성 생성 완료:", output_path)
PY
생성된 음성을 재생합니다.
aplay /tmp/huro_tts_test.wav
여기까지 정상적으로 동작하면 다음 항목이 모두 완료된 것입니다.
Google Cloud 프로젝트 정상
결제 계정 정상
Cloud Text-to-Speech API 활성화
서비스 계정 정상
IAM 권한 정상
JSON 인증 키 정상
TurtleBot3 환경변수 정상
Python 클라이언트 인증 정상
음성 합성 요청 정상
17. Cloud Console에서 API 사용량 확인
Google Cloud Console에서 다음 메뉴로 이동합니다.
API 및 서비스
→ 사용 설정된 API 및 서비스
→ Cloud Text-to-Speech API
→ 측정항목
영문 화면에서는 다음과 같습니다.
APIs & Services
→ Enabled APIs & services
→ Cloud Text-to-Speech API
→ Metrics
다음 항목을 확인할 수 있습니다.
API 요청 수
오류 수
지연 시간
할당량 사용량
할당량은 다음 메뉴에서 확인합니다.
Cloud Text-to-Speech API
→ 할당량 및 시스템 한도
Google Cloud Text-to-Speech에는 프로젝트 단위 요청 할당량이 있으며, 일부 음성 모델은 별도 할당량을 사용합니다. 현재 적용되는 정확한 값은 프로젝트의 할당량 화면에서 확인해야 합니다. 필요한 경우 Google Cloud Console에서 할당량 증가를 요청할 수 있습니다.
18. 요금 확인 방법
Cloud Text-to-Speech 요금은 일반적으로 합성 요청에 포함된 문자 수와 음성 모델 종류에 따라 계산됩니다.
공백도 문자 수에 포함되며 SSML을 사용할 경우 일부 태그도 계산 대상에 포함됩니다. Standard, WaveNet, Neural, Chirp 계열에 따라 무료 사용량과 단가가 다를 수 있습니다. 가격은 변경될 수 있으므로 실제 배포 전 공식 가격 페이지에서 현재 기준을 확인해야 합니다.
Google Cloud Console에서 실제 비용은 다음 메뉴에서 확인합니다.
결제
→ 보고서
필터를 다음과 같이 설정합니다.
프로젝트:
huro-tts-202608
서비스:
Cloud Text-to-Speech API
이렇게 설정하면 다른 Google Cloud 서비스 비용과 분리하여 확인할 수 있습니다.
19. JSON 키 교체 방법
서비스 계정 JSON 키는 영구적으로 사용하지 말고 주기적으로 교체하는 것이 좋습니다.
교체 순서는 다음과 같습니다.
새 JSON 키 생성
→ TurtleBot3에 새 키 복사
→ 환경변수 경로 확인
→ TTS 테스트
→ 기존 키 비활성화
→ 일정 기간 확인
→ 기존 키 삭제
새 키가 정상적으로 동작하는지 확인하기 전에 기존 키를 먼저 삭제하면 로봇의 TTS 기능이 중단될 수 있습니다.
키 관리 화면은 다음 위치입니다.
IAM 및 관리자
→ 서비스 계정
→ 서비스 계정 선택
→ 키
키가 유출되었다면 테스트 과정을 기다리지 말고 즉시 해당 키를 삭제해야 합니다.
20. 프로젝트를 사용하지 않을 때 정리하는 방법
실습이 끝나 더 이상 Google Cloud Text-to-Speech를 사용하지 않는다면 다음 중 하나를 선택합니다.
1) 서비스 계정 키만 삭제
IAM 및 관리자
→ 서비스 계정
→ 서비스 계정 선택
→ 키
→ 해당 키 삭제
TurtleBot3에 복사한 JSON 파일도 삭제합니다.
rm -f ~/.config/google/turtlebot3-tts.json
~/.bashrc에 추가한 환경변수도 제거합니다.
2) Text-to-Speech API 비활성화
API 및 서비스
→ 사용 설정된 API 및 서비스
→ Cloud Text-to-Speech API
→ API 사용 중지
API를 비활성화하면 해당 프로젝트에서 새로운 음성 합성 요청을 할 수 없습니다. Google Cloud 공식 문서에서는 API 개요 화면에서 Cloud Text-to-Speech API를 선택한 뒤 Disable API 버튼으로 비활성화할 수 있다고 안내합니다.
3) 프로젝트 삭제
프로젝트를 완전히 사용하지 않는다면 다음 메뉴로 이동합니다.
IAM 및 관리자
→ 설정
→ 종료
프로젝트 ID를 입력하여 삭제를 확인합니다.
프로젝트 삭제는 해당 프로젝트에 포함된 다른 Google Cloud 리소스에도 영향을 주므로 다른 서비스를 함께 사용하고 있는지 먼저 확인해야 합니다.