{"id":767,"library":"google-cloud-texttospeech","title":"Google Cloud Text-to-Speech","description":"The `google-cloud-texttospeech` client library for Python enables seamless integration with the Google Cloud Text-to-Speech API. It allows developers to convert text into natural-sounding speech using Google's advanced AI technologies, supporting a wide range of voices, languages, and customization options. As of version 2.35.0, it continues to be actively maintained with frequent updates as part of the broader Google Cloud Python client libraries.","status":"active","version":"2.35.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-texttospeech","tags":["google cloud","text-to-speech","tts","speech synthesis","audio","gcp"],"install":[{"cmd":"pip install google-cloud-texttospeech","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python >= 3.9","package":"Python","optional":false}],"imports":[{"note":"The TextToSpeechClient is the primary entry point for interacting with the API.","symbol":"TextToSpeechClient","correct":"from google.cloud import texttospeech"},{"note":"For access to enums (e.g., AudioEncoding, SsmlVoiceGender) and types (e.g., SynthesisInput, VoiceSelectionParams), it's common to import the versioned module and alias it.","symbol":"enums and types","correct":"from google.cloud import texttospeech_v1 as texttospeech"}],"quickstart":{"code":"import os\nfrom google.cloud import texttospeech_v1 as texttospeech\n\ndef synthesize_text(text):\n    \"\"\"Synthesizes speech from the input string of text.\n\n    Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable is set\n    or authenticate using `gcloud auth application-default login`.\n    \"\"\"\n\n    # Instantiates a client\n    client = texttospeech.TextToSpeechClient()\n\n    # Set the text input to be synthesized\n    synthesis_input = texttospeech.SynthesisInput(text=text)\n\n    # Build the voice request, select the language code ('en-US') and the SSML voice gender ('NEUTRAL')\n    voice = texttospeech.VoiceSelectionParams(\n        language_code=\"en-US\",\n        ssml_gender=texttospeech.SsmlVoiceGender.NEUTRAL,\n    )\n\n    # Select the type of audio file you want returned\n    audio_config = texttospeech.AudioConfig(\n        audio_encoding=texttospeech.AudioEncoding.MP3\n    )\n\n    # Perform the text-to-speech request\n    response = client.synthesize_speech(\n        input=synthesis_input,\n        voice=voice,\n        audio_config=audio_config\n    )\n\n    # The response's audio_content is binary. Write it to a file.\n    output_filename = \"output.mp3\"\n    with open(output_filename, \"wb\") as out:\n        out.write(response.audio_content)\n    print(f'Audio content written to file \"{output_filename}\"')\n\nif __name__ == \"__main__\":\n    # For local development, set the GOOGLE_APPLICATION_CREDENTIALS environment variable.\n    # For example: os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = '/path/to/your/key.json'\n    # Or use `gcloud auth application-default login`\n    if not os.environ.get('GOOGLE_APPLICATION_CREDENTIALS'):\n        print(\"Warning: GOOGLE_APPLICATION_CREDENTIALS not set. Assuming gcloud ADC is configured.\")\n\n    text_to_synthesize = \"Hello, world! This is a test of the Google Cloud Text-to-Speech API.\"\n    synthesize_text(text_to_synthesize)","lang":"python","description":"This quickstart synthesizes a given text into an MP3 audio file. It demonstrates client initialization, defining input text, selecting a voice, configuring audio output, and saving the generated speech. Ensure you have authenticated to Google Cloud, typically via the `GOOGLE_APPLICATION_CREDENTIALS` environment variable or `gcloud auth application-default login`."},"warnings":[{"fix":"Regularly check the Cloud Text-to-Speech release notes for voice updates. Consider using `client.list_voices()` to programmatically discover available voices and their names, and implement a fallback mechanism for voice selection. Test your application's voice output after significant service updates.","message":"Google Cloud Text-to-Speech voices are periodically updated or replaced. Existing voice names in your application might be deprecated or behave differently, potentially causing unexpected audio output or errors.","severity":"breaking","affected_versions":"All versions (service-side changes)"},{"fix":"Ensure you have enabled the Text-to-Speech API in your Google Cloud project and set up authentication. For local development, use `gcloud auth application-default login` or set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file. For production, refer to the ADC documentation.","message":"Incorrect authentication setup is a common issue. If `GOOGLE_APPLICATION_CREDENTIALS` is not set or Application Default Credentials (ADC) are not configured, the client will fail to connect to the API.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always refer to the official documentation or use the `client.list_voices()` method to get a current list of supported voices, their language codes, and SSML genders. This ensures compatibility and avoids errors due to incorrect voice parameters.","message":"Using an invalid `language_code`, `name`, or `ssml_gender` in `VoiceSelectionParams` can lead to `InvalidArgument` errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your development and deployment environments use Python 3.9 or newer. Upgrade your Python installation if necessary.","message":"The minimum supported Python version for `google-cloud-texttospeech` is `3.9`. Using older Python versions can lead to installation issues or runtime errors.","severity":"gotcha","affected_versions":"< 2.x (older docs sometimes mentioned 3.7+), >=2.x requires 3.9+"}],"env_vars":null,"last_verified":"2026-05-12T18:49:15.893Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Ensure you have the correct library installed by running: `pip install --upgrade google-cloud-texttospeech`. If you previously installed `google-cloud`, uninstall it with `pip uninstall google-cloud` first.","cause":"This error occurs when the `google-cloud-texttospeech` library is not correctly installed in the Python environment, or if an old, deprecated `google-cloud` meta-package is installed instead of the specific client library.","error":"ModuleNotFoundError: No module named 'google.cloud'"},{"fix":"Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the absolute path of your service account JSON key file. On Linux/macOS: `export GOOGLE_APPLICATION_CREDENTIALS=\"/path/to/your/key.json\"`. On Windows (Command Prompt): `set GOOGLE_APPLICATION_CREDENTIALS=\"C:\\path\\to\\your\\key.json\"`. Alternatively, use `gcloud auth application-default login` for local development.","cause":"The application cannot find the necessary Google Cloud credentials to authenticate with the Text-to-Speech API. This typically means the `GOOGLE_APPLICATION_CREDENTIALS` environment variable is not set or points to an invalid or non-existent service account key file.","error":"DefaultCredentialsError: Could not automatically determine credentials. Please set GOOGLE_APPLICATION_CREDENTIALS"},{"fix":"Update the `google-cloud-texttospeech` library to the latest version (`pip install --upgrade google-cloud-texttospeech`). If the error persists, check the official client library documentation for the correct way to import and use API types, as the structure might have changed (e.g., `texttospeech.SynthesisInput` directly instead of `texttospeech.types.SynthesisInput`).","cause":"This error usually indicates a version incompatibility where the code is using an older syntax (e.g., `texttospeech.types.SynthesisInput`) that is no longer valid for the installed version of the `google-cloud-texttospeech` library, or vice-versa.","error":"AttributeError: module 'google.cloud.texttospeech' has no attribute 'types'"},{"fix":"Go to the Google Cloud Console, select your project, navigate to 'APIs & Services' > 'Enabled APIs & Services', and ensure that the 'Cloud Text-to-Speech API' is enabled. Also, verify that your service account has roles such as 'Cloud Text-to-Speech User' or a custom role with appropriate permissions.","cause":"The Google Cloud Text-to-Speech API is not enabled for the specific Google Cloud project being used, or the service account lacks the necessary permissions to access it.","error":"Forbidden: 403 POST Cloud Text-to-Speech API has not been used in project # before or it is disabled."},{"fix":"Review your API usage in the Google Cloud Console ('IAM & Admin' > 'Quotas') for the Text-to-Speech API. You can request a quota increase if needed. For requests exceeding content limits, use asynchronous methods or process smaller chunks of text.","cause":"Your Google Cloud project has exceeded the allocated quota for the Text-to-Speech API, such as the number of characters synthesized per minute or total bytes per request.","error":"RESOURCE_EXHAUSTED: Quota exceeded."}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"2.36.0","cli_name":"","cli_version":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":null,"pypi_latest":"2.36.0","is_stale":null,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.87,"mem_mb":23.6,"disk_size":"69.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.84,"mem_mb":23.8,"disk_size":"68.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":6.2,"import_time_s":1.13,"mem_mb":20.6,"disk_size":"67M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.09,"mem_mb":20.8,"disk_size":"66M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.33,"mem_mb":25.6,"disk_size":"73.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.66,"mem_mb":25.8,"disk_size":"72.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":5.2,"import_time_s":1.66,"mem_mb":22.8,"disk_size":"72M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.57,"mem_mb":23.1,"disk_size":"70M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.43,"mem_mb":24.8,"disk_size":"65.3M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.76,"mem_mb":25.6,"disk_size":"64.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":4.3,"import_time_s":2.04,"mem_mb":22.1,"disk_size":"63M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.52,"mem_mb":22.9,"disk_size":"62M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.3,"mem_mb":25.8,"disk_size":"65.0M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.71,"mem_mb":26.3,"disk_size":"63.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":4.6,"import_time_s":1.86,"mem_mb":23,"disk_size":"63M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.31,"mem_mb":23.5,"disk_size":"62M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.66,"mem_mb":23.5,"disk_size":"69.2M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.57,"mem_mb":23.3,"disk_size":"68.1M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":null,"install_time_s":7.1,"import_time_s":1.37,"mem_mb":20.6,"disk_size":"67M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"google-cloud-texttospeech","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.15,"mem_mb":20.4,"disk_size":"66M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}