[Bug]: Issue in sending multiple Keyterms

[AghashNair]

Summary

Issue in sending multiple keyterms.

What happened?

Actual
Currently using v5.3 of the sdk. While attempting to send multiple keyterms (keywords for nova2) for AsyncDeepgramClient.listen.v1.connect and AsyncDeepgramClient.listen.v2.connect. Accepted param is string. not list of string, raises an unexpected body error while passing a list of string.

Using both flux and nova3

Currently seen within the sdk is

query_params = httpx.QueryParams()
query_params = query_params.add("keyterm", keyterm)

gives a result of keyterm=%5B%27KEYTERM1%27%2C+%27KEYTERM2%27%5D

Expected
As per official documentation of sending keyterm, the terms that have to be considered as stand alonde need to be sent in the format
--url "https://api.deepgram.com/v1/listen?model=nova-3&keyterm=KEYTERM1&keyterm=KEYTERM2"
Is there a known alternative to send multiple keyterms

Steps to reproduce

1. Install deepgram-sdk==5.3.0
2. Use snippet below

Minimal code sample

from deepgram import AsyncDeepgramClient


client = AsyncDeepgramClient(api_key="USE_OWN_API_KEY")
async def connect():   
    async with client.listen.v2.connect(
         model= "flux-general-en",
         encoding= "linear16",
         sample_rate= "16000",    
         eot_threshold= "0.8",
         eager_eot_threshold= "0.8",
         keyterm=["KEYTERM1","KEYTERM2"]
    ) as connection:
                print("works")

Logs / traceback

Transport

WebSocket

API endpoint / path

/v2/listen

Model(s) used

nova-2,nova-3, flux-general-en

How often?

Always

Is this a regression?

• Yes, it worked in an earlier version

Last working SDK version (if known)

No response

SDK version

5.3.0

Python version

3.12.3

Install method

None

OS

Linux (x86_64)

Environment details

Link to minimal repro (optional)

No response

Session ID (optional)

No response

Project ID (optional)

No response

Request ID (optional)

No response

Code of Conduct

• I agree to follow this project’s Code of Conduct

[naomi-lgbt]

Hey there,

I put together a minimal viable example:

from deepgram import AsyncDeepgramClient
from deepgram.core.events import EventType
from deepgram.extensions.types.sockets import ListenV1SocketClientResponse
import asyncio
print("Connecting to Deepgram...")
client = AsyncDeepgramClient(api_key="")
async def connect():
    try: 
        async with client.listen.v2.connect(
            model= "flux-general-en",
            encoding= "linear16",
            sample_rate= "16000",    
            eot_threshold= "0.8",
            eager_eot_threshold= "0.8",
            keyterm=["KEYTERM1","KEYTERM2"],
        ) as connection:
                def on_message(message: ListenV1SocketClientResponse) -> None:
                    msg_type = getattr(message, "type", "Unknown")
                    print(f"Received {msg_type} event")
                    print(message)
            
                connection.on(EventType.OPEN, lambda _: print("Connection opened"))
                connection.on(EventType.MESSAGE, on_message)
                connection.on(EventType.CLOSE, lambda _: print("Connection closed"))
                connection.on(EventType.ERROR, lambda error: print(f"Caught: {error}"))

                # EXAMPLE ONLY: Start listening task and cancel after brief demo
                # In production, you would typically await connection.start_listening() directly
                # which runs until the connection closes or is interrupted
                listen_task = asyncio.create_task(connection.start_listening())
                await asyncio.sleep(3)  # EXAMPLE ONLY: Wait briefly to see some events before exiting
                listen_task.cancel()
    except Exception as e:
        print(f"Caught: {e}")
if __name__ == "__main__":
    asyncio.run(connect())

I added a log to print the web socket URL, and I do see the weird parsing that you did, but I am not getting back an API error.

Connecting to Deepgram...
wss://api.deepgram.com/v2/listen?model=flux-general-en&encoding=linear16&sample_rate=16000&eager_eot_threshold=0.8&eot_threshold=0.8&keyterm=%5B%27KEYTERM1%27%2C+%27KEYTERM2%27%5D
Connection opened
Received Connected event
type='Connected' request_id='4bdf2b3c-f32b-42b0-be54-a2d8aa433d3b' sequence_id=0
Connection closed

If I fire up a full example from our docs:

# Example filename: main.py

# For help migrating to the new Python SDK, check out our migration guide:
# https://github.com/deepgram/deepgram-python-sdk/blob/main/docs/Migrating-v3-to-v5.md

# Set your Deepgram API key as an environment variable:
# export DEEPGRAM_API_KEY="your-api-key-here"

import httpx
import logging
import threading

from deepgram import (
    DeepgramClient,
)
from deepgram.core.events import EventType
from deepgram.extensions.types.sockets import ListenV1SocketClientResponse

# URL for the realtime streaming audio you would like to transcribe
URL = "http://stream.live.vc.bbcmedia.co.uk/bbc_world_service"

def main():
    try:
        # use default config
        deepgram: DeepgramClient = DeepgramClient(api_key="")

        # Create a websocket connection to Deepgram
        with deepgram.listen.v1.connect(model="nova-3", keyterm=["KEYTERM1","KEYTERM2"]) as connection:
            def on_message(message: ListenV1SocketClientResponse) -> None:
                msg_type = getattr(message, "type", "Unknown")
                if hasattr(message, 'channel') and hasattr(message.channel, 'alternatives'):
                    sentence = message.channel.alternatives[0].transcript
                    if len(sentence) == 0:
                        return
                    print(message.channel.json(indent=4))

            connection.on(EventType.OPEN, lambda _: print("Connection opened"))
            connection.on(EventType.MESSAGE, on_message)
            connection.on(EventType.CLOSE, lambda _: print("Connection closed"))
            connection.on(EventType.ERROR, lambda error: print(f"Error: {error}"))

            lock_exit = threading.Lock()
            exit = False

            # Define a thread for start_listening with error handling
            def listening_thread():
                try:
                    connection.start_listening()
                except Exception as e:
                    print(f"Error in listening thread: {e}")

            # Start listening in a separate thread
            listen_thread = threading.Thread(target=listening_thread)
            listen_thread.start()

            # define a worker thread for HTTP streaming with error handling
            def myThread():
                try:
                    with httpx.stream("GET", URL) as r:
                        for data in r.iter_bytes():
                            lock_exit.acquire()
                            if exit:
                                break
                            lock_exit.release()

                            connection.send_media(data)
                except Exception as e:
                    print(f"Error in HTTP streaming thread: {e}")

            # start the HTTP streaming thread
            myHttp = threading.Thread(target=myThread)
            myHttp.start()

            # signal finished
            input("")
            lock_exit.acquire()
            exit = True
            lock_exit.release()

            # Wait for both threads to close and join with timeout
            myHttp.join(timeout=5.0)
            listen_thread.join(timeout=5.0)

            print("Finished")

    except Exception as e:
        print(f"Could not open socket: {e}")
        return

if __name__ == "__main__":
    main()

I successfully get transcription responses back from the API.

---

Given this, I'm afraid I need some additional information on when and where you are seeing the exact error so I can narrow down my investigation and determine the priority of the issue.

[hongyiweiwu01]

Hey @naomi-lgbt -- we're running into the issue where the keyterm parameter is typed as Optional[str] in the listen v2 client's type signature that even if we could pass an array to it and the SDK doesn't error out, the type checker would fail. We would need to disable the type checker for that line which is not ideal.

[lukeocodes]

This issue has been fixed in PR #650! 🎉

The WebSocket clients now properly handle array parameters for keyterms and other parameters. Arrays are correctly expanded into multiple query parameters (e.g., keyterm=term1&keyterm=term2) instead of being URL-encoded as a single stringified array.

What's fixed:

• Both client.listen.v1.connect and client.listen.v2.connect now accept arrays for keyterm and other parameters
• Arrays are properly serialized to match the API expectations
• Type signatures updated to typing.Union[str, typing.Sequence[str]] for proper type checking

Your example now works:

async with client.listen.v2.connect(
    model="flux-general-en",
    encoding="linear16",
    sample_rate="16000",
    eot_threshold="0.8",
    eager_eot_threshold="0.8",
    keyterm=["KEYTERM1", "KEYTERM2"]  # ✅ Now works correctly!
) as connection:
    print("works")

The fix will be available in the next SDK release.