IBM Watson Python SDK

11.2.0 verified Fri May 01 auth: no python

The official Python client library for IBM Watson services, including Speech to Text, Text to Speech, Assistant, Natural Language Understanding, and more. Current version 11.2.0, released January 2026. Maintained actively by IBM.

pip install ibm-watson

Common errors

error ImportError: cannot import name 'ApiException' from 'ibm_watson' ↓

cause ApiException is not part of ibm-watson; it is in ibm-cloud-sdk-core.

fix

Use: from ibm_cloud_sdk_core import ApiException

error AttributeError: module 'ibm_watson' has no attribute 'SpeechToTextV1' ↓

cause Possible import of Python file named 'ibm_watson.py' that shadows the package, or using an old import path.

fix

Ensure your script is not named 'ibm_watson.py'. Use: from ibm_watson import SpeechToTextV1

error TypeError: createSession() missing 1 required positional argument: 'environment_id' ↓

cause Assistant V2 session methods now require an 'environmentId' parameter since version 11.0.0.

fix

Call: assistant.create_session(assistant_id='...', environment_id='...')

error WatsonApiException: Error: Unauthorized, Code: 401 ↓

cause Invalid API key or the authenticator is not configured correctly.

fix

Verify your API key and ensure you use IAMAuthenticator(api_key). Also check service URL region.

Warnings

breaking Version 11.0.0+ requires 'environmentId' parameter in Assistant V2 'createSession' and 'deleteSession' methods. ↓

fix Add the 'environmentId' argument when calling create_session() or delete_session().

breaking Version 10.0.0 removed 'interim_results' and 'low_latency' WebSocket parameters from Speech to Text. ↓

fix Remove these parameters from your recognize_with_websocket() calls.

breaking Version 9.0.0 introduced breaking changes in Discovery V2 batch API endpoints. ↓

fix Update Discovery V2 code to use the new batches APIs (e.g., list_batches, get_batch).

deprecated Old import paths like 'from watson_developer_cloud import ...' are deprecated and removed in recent versions. ↓

fix Use 'from ibm_watson import ...' instead.

gotcha Speech to Text WebSocket streaming requires the 'websocket-client' package to be installed separately. ↓

fix Install websocket-client: pip install websocket-client. It is a dependency but may be missed in some environments.

Install

pip install ibm-watson==11.2.0

Imports

SpeechToTextV1
wrong
```
from watson_developer_cloud import SpeechToTextV1
```
correct
```
from ibm_watson import SpeechToTextV1
```
The old package name 'watson_developer_cloud' is deprecated. Use 'ibm_watson'.
AssistantV2
wrong
```
from ibm_watson.assistant_v2 import AssistantV2
```
correct
```
from ibm_watson import AssistantV2
```
Direct import from ibm_watson is correct; the submodule path is outdated.

TextToSpeechV1

wrong

from ibm_watson.text_to_speech import TextToSpeechV1

correct

from ibm_watson import TextToSpeechV1

Use top-level import from ibm_watson.

NaturalLanguageUnderstandingV1

wrong

from ibm_watson.natural_language_understanding import NaturalLanguageUnderstandingV1

correct

from ibm_watson import NaturalLanguageUnderstandingV1

Top-level import is preferred.

ApiException

wrong

from ibm_watson import ApiException

correct

from ibm_cloud_sdk_core import ApiException

ApiException lives in ibm_cloud_sdk_core, not ibm_watson.

Quickstart

Initialize Speech to Text service with IAM authentication and transcribe an audio file.

from ibm_watson import SpeechToTextV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('your-api-key')
stt = SpeechToTextV1(authenticator=authenticator)
stt.set_service_url('https://api.us-south.speech-to-text.watson.cloud.ibm.com/instances/your-instance-id')

# Example: transcribe an audio file
with open('audio.wav', 'rb') as audio_file:
    result = stt.recognize(audio=audio_file, content_type='audio/wav').get_result()
print(result)