음성 리믹스로 커스텀 음성 만들기

음성 리믹스 기능을 사용하여 기존 음성을 수정하여 새 커스텀 음성을 만들 수 있습니다. 음성을 처음부터 설명하는 대신 기본 음성을 선택하고 연령, 음조, 에너지, 음색, 억양과 같은 변경사항을 설명합니다. Voices API는 결과를 프로젝트에 새 음성으로 저장하고 음성 생성 요청에 전달하는 재사용 가능한 voice_... ID를 반환합니다.

다음 음성을 리믹스할 수 있습니다.

리믹스된 음성은 Gemini 3.8 Flash TTS(gemini-3.8-flash-tts) 및 Gemini 3.8 Flash-Lite TTS(gemini-3.8-flash-lite-tts)와 모두 호환됩니다.

음성 리믹스 작동 방식

음성 리믹스는 음성 디자인과 동일한 Voices API create 메서드를 사용하며 voice.prompted.base_voice 필드가 추가됩니다.

  1. 기본 음성을 선택하고 변경사항 설명: voice.type를 VOICE_TYPE_PROMPTED로, store를 true로, voice.prompted.base_voice를 기존 음성의 이름 또는 ID로, voice.prompted.input를 변경사항에 대한 설명으로 설정하여 Voices API create 메서드를 호출합니다.
  2. 새 음성 ID 및 샘플 수신: Voices API는 기본 음성에 변경사항을 적용하고 결과를 프로젝트에 새 음성으로 저장하고 id 필드에 ID(예: voice_abc123...)를, sample_audio 필드에 음성 샘플을 반환합니다. 기본 음성은 변경되지 않습니다.
  3. 음성 생성 또는 다시 리믹스: generateContent 또는 streamGenerateContent를 호출할 때 speechConfig.voiceConfig.voice에 새 음성 ID를 전달합니다. 음성을 더 세부적으로 조정하려면 새 음성 ID를 다른 create 요청의 base_voice로 전달합니다.

시작하기 전에

  1. Google Cloud CLI를 설치합니다.

  2. gcloud CLI에서 제휴 ID를 사용하도록 구성합니다.

    자세한 내용은 제휴 ID로 gcloud CLI에 로그인을 참조하세요.

  3. gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

    gcloud init
  4. Cloud de Confiance 프로젝트를 만들거나 선택합니다.

    프로젝트를 선택하거나 만드는 데 필요한 역할

    • 프로젝트 선택: 프로젝트를 선택하는 데 특정 IAM 역할이 필요하지 않습니다. 역할이 부여된 모든 프로젝트를 선택할 수 있습니다.
    • 프로젝트 만들기: 프로젝트를 만들려면 resourcemanager.projects.create 권한이 포함된 프로젝트 생성자 역할(roles/resourcemanager.projectCreator)이 필요합니다. 역할 부여 방법 알아보기
    • Cloud de Confiance 프로젝트를 만듭니다.

      gcloud projects create PROJECT_ID

      PROJECT_ID를 만들려는 Cloud de Confiance 프로젝트의 이름으로 바꿉니다.

    • 만든 Cloud de Confiance 프로젝트를 선택합니다.

      gcloud config set project PROJECT_ID

      PROJECT_ID을 Cloud de Confiance 프로젝트 이름으로 바꿉니다.

  5. 이 가이드에 기존 프로젝트를 사용하는 경우 이 가이드를 완료하는 데 필요한 권한이 있는지 확인합니다. 새 프로젝트를 만든 경우에는 이미 필요한 권한이 있습니다.

  6. Cloud de Confiance 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  7. Agent Platform API가 아직 사용 설정되지 않은 경우 사용 설정합니다.

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할(roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할(roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기

    gcloud services enable aiplatform.googleapis.com
  8. 사용자 계정의 로컬 인증 사용자 인증 정보를 만듭니다.

    gcloud auth application-default login

    인증 오류가 반환되면 제휴 ID로 gcloud CLI에 로그인했는지 확인합니다.

Python 샘플을 사용하려면 Google 생성형 AI SDK 버전 2.33.0 이상을 설치합니다.

pip install --upgrade "google-genai>=2.33.0"

Voices API는 v1beta1 API 버전을 통해 global 위치에서 사용할 수 있습니다.

필요한 역할

음성을 리믹스하고 음성을 생성하는 데 필요한 권한을 얻으려면 관리자에게 Cloud de Confiance by S3NS 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

리믹스 음성 만들기

요청에서 다음 필드를 설정합니다.

  • store: true이어야 합니다. 리믹스된 음성은 항상 프로젝트에 저장됩니다. store: false로 base_voice를 설정하는 요청은 INVALID_ARGUMENT 오류와 함께 실패합니다.
  • voice.type: VOICE_TYPE_PROMPTED.
  • voice.prompted.base_voice: 리믹스할 음성입니다. 사전 빌드된 음성(예: Puck)의 음성 이름, 확장 음성 라이브러리 음성의 음성 ID 또는 설계되거나 리믹스된 음성의 voice_... ID를 사용합니다. 음성이 없으면 NOT_FOUND 오류와 함께 요청이 실패합니다.
  • voice.prompted.input: 기본 음성에 적용할 변경사항에 대한 자연어 설명입니다.
  • voice.display_name, voice.gender, voice.language_code: 새 음성의 선택적 메타데이터입니다.

voice.model 설정 안 함 store: true와 함께 모델을 설정하는 요청은 INVALID_ARGUMENT 오류와 함께 실패합니다.

음성을 리믹스하는 데 몇 초 정도 걸릴 수 있습니다. Python 샘플은 요청 제한 시간을 60초로 설정합니다.

응답에는 다음 필드가 포함됩니다.

  • id: 새 음성의 ID입니다.
  • prompted.base_voice: 리믹스한 기본 음성입니다.
  • sample_audio: 새 음성의 샘플입니다. data 필드에는 base64로 인코딩된 오디오가 포함되고 mime_type 필드에는 인코딩 이름이 지정됩니다. 기본적으로 샘플은 RIFF 헤더가 있는 완전한 WAV 파일(audio/wav)입니다(16비트 PCM, 24kHz, 모노). 일부 음성은 헤더 없는 16비트 PCM(audio/l16; rate=24000; channels=1)을 대신 반환할 수 있으므로 오디오를 저장하기 전에 mime_type를 확인하세요.
  • usage: 요청에서 사용한 토큰 수입니다. 자세한 내용은 가격 책정을 참조하세요.

다음 샘플은 사전 빌드된 Puck 음성을 리믹스합니다.

Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참고하세요.

Vertex AI에서 Google 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다.

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import base64
import wave

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

voice = client.voices.create(
    store=True,
    voice={
        "type": "VOICE_TYPE_PROMPTED",
        "display_name": "Older British Puck",
        "prompted": {
            "base_voice": "Puck",
            "input": (
                "Make the voice sound slightly older and more grounded, with a"
                " warm British accent and measured audiobook narration pacing."
            ),
        },
    },
    timeout=60,
)

print(f"Created voice ID: {voice.id}")

# Save the voice sample. The SDK returns sample_audio.data as a base64
# string. By default, it's a complete WAV file (audio/wav). For
# compatibility, add a WAV header if the sample is raw 16-bit PCM
# (audio/l16).
sample = base64.b64decode(voice.sample_audio.data)
if voice.sample_audio.mime_type.lower().startswith("audio/l16"):
    with wave.open("remixed_voice_sample.wav", "wb") as wf:
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)
        wf.writeframes(sample)
else:
    with open("remixed_voice_sample.wav", "wb") as f:
        f.write(sample)

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.

HTTP 메서드 및 URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices

JSON 요청 본문:

{
  "store": true,
  "voice": {
    "type": "VOICE_TYPE_PROMPTED",
    "displayName": "Older British Puck",
    "prompted": {
      "baseVoice": "Puck",
      "input": "Make the voice sound slightly older and more grounded, with a warm British accent and measured audiobook narration pacing."
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 수신됩니다. sample_audio.data 필드가 잘립니다.

{
  "id": "voice_7bd85ebf-761b-4969-8544-4ec60f06d124",
  "prompted": {
    "base_voice": "Puck"
  },
  "usage": {
    "total_tokens": 578,
    "total_input_tokens": 297,
    "input_tokens_by_modality": [
      {"modality": "text", "tokens": 38},
      {"modality": "audio", "tokens": 259}
    ],
    "total_output_tokens": 281,
    "output_tokens_by_modality": [
      {"modality": "audio", "tokens": 281}
    ]
  },
  "sample_audio": {
    "mime_type": "audio/wav",
    "data": "UklGRpTwAwBXQVZF..."
  }
}

기본적으로 sample_audio.mime_type는 audio/wav이고 sample_audio.data는 base64로 인코딩된 전체 WAV 파일을 보유합니다. mime_type가 audio/l16이면 디코딩된 데이터는 24kHz의 헤더 없는 16비트 PCM 오디오, 모노이며 대부분의 플레이어에서 열 수 있으려면 WAV 헤더가 필요합니다.

리믹스된 음성으로 음성 생성

설계된 음성을 전달하는 것과 동일한 방식으로 speechConfig.voiceConfig.voice에 음성 ID를 전달합니다.

Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참고하세요.

Vertex AI에서 Google 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다.

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Chapter One. The fog rolled quietly across the harbor at dawn.",
            "speech_metadata": {"style": "calm and reflective"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {"voice_config": {"voice": "VOICE_ID"}},
    },
)

# The SDK has already decoded the base64 audio, so inline_data.data is a
# complete WAV file by default.
with open("remixed_voice.wav", "wb") as f:
    f.write(response.candidates[0].content.parts[0].inline_data.data)

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • VOICE_ID: Voices API create 메서드에서 반환한 음성 ID입니다.

HTTP 메서드 및 URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent

JSON 요청 본문:

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "Chapter One. The fog rolled quietly across the harbor at dawn.",
      "speechMetadata": {"style": "calm and reflective"}
    }]
  }],
  "generationConfig": {
    "responseModalities": ["AUDIO"],
    "speechConfig": {
      "voiceConfig": {"voice": "VOICE_ID"}
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent" | Select-Object -Expand Content

응답에는 오디오가 candidates[0].content.parts[0].inlineData.data에 base64로 인코딩된 완전한 WAV 파일로 포함됩니다. data 필드가 잘립니다.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "audio/wav",
              "data": "UklGRhRlBABXQVZF..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

Python 샘플에서 PROJECT_ID를 Cloud de Confiance by S3NS프로젝트 ID로 바꾸고 VOICE_ID를 create 메서드가 반환한 음성 ID로 바꿉니다.

단계별로 음성 미세 조정하기

리믹스된 각 음성은 저장된 voice_... 음성이므로 다른 리믹스의 기본 음성으로 사용할 수 있습니다. 이 단계별 워크플로를 사용하면 한 번에 하나 또는 두 개의 특성을 변경하고 각 결과를 들은 후 다음 변경을 수행할 수 있습니다. 디자인된 음성으로 시작할 수도 있습니다.

다음 샘플은 기존에 설계되거나 리믹스된 음성을 리믹스합니다.

Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참고하세요.

Vertex AI에서 Google 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다.

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

voice = client.voices.create(
    store=True,
    voice={
        "type": "VOICE_TYPE_PROMPTED",
        "prompted": {
            "base_voice": "BASE_VOICE_ID",
            "input": (
                "Keep the same speaker identity and accent, but make the"
                " delivery calmer, softer, and slightly lower in pitch."
            ),
        },
    },
    timeout=60,
)

print(f"Created voice ID: {voice.id}")
print(f"Remixed from: {voice.prompted.base_voice}")

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • BASE_VOICE_ID: 프로젝트에서 설계되거나 리믹스된 음성의 voice_... ID입니다.

HTTP 메서드 및 URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices

JSON 요청 본문:

{
  "store": true,
  "voice": {
    "type": "VOICE_TYPE_PROMPTED",
    "prompted": {
      "baseVoice": "BASE_VOICE_ID",
      "input": "Keep the same speaker identity and accent, but make the delivery calmer, softer, and slightly lower in pitch."
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 수신됩니다. sample_audio.data 필드가 잘립니다.

{
  "id": "voice_f70c942e-7d78-427d-8466-cae3cb9b0371",
  "prompted": {
    "base_voice": "voice_7bd85ebf-761b-4969-8544-4ec60f06d124"
  },
  "sample_audio": {
    "mime_type": "audio/wav",
    "data": "UklGRhT4AgBXQVZF..."
  }
}

Python 샘플에서 BASE_VOICE_ID를 프로젝트에서 설계되거나 리믹스된 음성의 voice_... ID로 바꿉니다.

리믹스된 음성 관리

리믹스된 음성은 설계된 음성과 동일한 유형인 VOICE_TYPE_PROMPTED 유형으로 프로젝트에 저장됩니다. 리믹스된 음성을 나열, 가져오기, 삭제하려면 설계된 음성과 동일한 메서드를 사용합니다. 자세한 내용은 저장된 음성 관리를 참고하세요.

리믹스된 음성은 기본 음성과 독립적입니다.

  • 리믹스해도 기본 음성은 변경되지 않습니다.
  • 기본 음성을 삭제해도 해당 음성에서 리믹스된 음성에는 영향을 미치지 않습니다.

한도

  • 저장된 음성은 마지막으로 사용한 후 1년이 지나면 만료됩니다. 음성으로 음성을 생성하거나 리믹스의 base_voice로 사용하면 이 기간이 다시 시작됩니다. 더 이상 필요하지 않은 음성을 삭제합니다.
  • 리믹스 요청은 음성 디자인 및 음성 복제와 동일한 프로젝트별 분당 음성 생성 할당량에 반영됩니다. 이 한도를 초과하면 create 메서드가 RESOURCE_EXHAUSTED 오류를 반환합니다. 잠시 후에 다시 시도하세요. 자세한 내용은 할당량 및 시스템 한도를 참조하세요.

가격 책정

음성 리믹스는 다음 토큰에 대해 Gemini 3.8 Flash TTS 요금으로 청구됩니다.

  • voice.prompted.input의 설명에 대한 텍스트 입력 토큰입니다.
  • 기본 음성 오디오의 오디오 입력 토큰입니다.
  • Voices API에서 생성하는 음성 샘플의 오디오 출력 토큰

create 응답의 usage 필드는 각 개수를 보고합니다. 예를 들어 샘플 만들기의 리믹스는 약 40개의 텍스트 입력 토큰, 약 260개의 오디오 입력 토큰, 약 280개의 오디오 출력 토큰을 사용합니다.

get, list, delete 메서드는 청구되지 않습니다. 리믹스된 음성으로 생성하는 음성은 호출하는 모델의 요율로 청구됩니다.

토큰 요금은 Gemini Enterprise 가격 책정을 참조하세요.

프롬프트 권장사항

  • 변경사항만 설명: 모델은 기본 음성의 소리를 유지하므로 연령, 음색, 음조, 속도, 에너지와 같이 변경할 특성만 설명합니다. 음성에 대한 전체 설명을 반복하지 마세요.
  • 새로운 언어 또는 억양을 명시적으로 지정: 리믹스는 voice.prompted.input가 다른 언어 또는 억양을 요청하지 않는 한 기본 음성의 언어와 지역 억양을 유지합니다.
  • 단계별로 한두 가지 특성 변경: 여러 리믹스에서 음성을 미세 조정할 때는 각 요청에서 소수의 특성을 변경하고 다음 변경을 수행하기 전에 sample_audio를 들어보세요.
  • 영구적인 특성에 리믹스 사용 및 각 차례에 speech_metadata.style 사용: 음성 리믹스를 사용하여 연령, 억양, 피치, 페르소나와 같은 음성의 기준을 변경합니다. "whispered urgently" 또는 "excited"와 같은 짧은 speech_metadata.style 값을 사용하여 개별 차례의 전달을 지시합니다.

다음 표에는 리믹스 요청의 예가 나와 있습니다.

목표 base_voice prompted.input
연령 및 음색 변경 Puck Make the voice sound 20 years older with a deeper, slightly gravelly baritone timbre while keeping the friendly warmth.
지역 억양 변경 Kore Change the accent to Australian English while preserving the clear, confident studio delivery.
도메인에 적응 설계된 음성(voice_...) Adapt this voice for late-night meditation narration: lower the vocal projection, slow the pacing, and soften the tone.
에너지 증진 리믹스된 음성(voice_...) Increase vocal energy and projection so the speaker sounds like an upbeat live event announcer.

다음 단계

  • 음성 디자인을 사용하여 텍스트 설명에서 커스텀 음성을 만듭니다.
  • 음성 복제를 사용하여 기존 화자의 음성을 복제합니다.
  • Gemini TTS로 음성 생성에서 발화 수준 스타일 지정, 인라인 태그, 다중 화자 대화에 대해 알아보세요.