sambanova/sambanova-python

sambanova/sambanova-python

Language: Python

License: Apache-2.0

Stars: 2

Forks: 0

Open issues: 0

Created: 2025-08-20T22:16:11Z

Pushed: 2026-05-26T21:57:51Z

Default branch: main

Fork: no

Archived: no

README:

Samba Nova Python API library

The Samba Nova Python library provides convenient access to the Samba Nova REST API from any Python 3.9+ application. The library includes type definitions for all request params and response fields, and offers both synchronous and asynchronous clients powered by httpx.

It is generated with Stainless.

Documentation

The REST API documentation can be found on docs.sambanova.ai. The full API of this library can be found in [api.md](api.md).

Installation

# install from PyPI
pip install sambanova

Usage

The full API of this library can be found in [api.md](api.md).

import os
from sambanova import SambaNova

client = SambaNova(
api_key=os.environ.get("SAMBANOVA_API_KEY"), # This is the default and can be omitted
)

completion = client.chat.completions.create(
messages=[
{
"content": "create a poem using palindromes",
"role": "user",
}
],
model="gpt-oss-120b",
)

Responses API

import os
from sambanova import SambaNova

client = SambaNova(
api_key=os.environ.get("SAMBANOVA_API_KEY"),
)

response = client.responses.create(
model="gpt-oss-120b",
input="Explain disestablishmentarianism to a smart five year old.",
)
print(response.output_text)

While you can provide an api_key keyword argument, we recommend using python-dotenv to add SAMBANOVA_API_KEY="My API Key" to your .env file so that your API Key is not stored in source control.

Async usage

Simply import AsyncSambaNova instead of SambaNova and use await with each API call:

import os
import asyncio
from sambanova import AsyncSambaNova

client = AsyncSambaNova(
api_key=os.environ.get("SAMBANOVA_API_KEY"), # This is the default and can be omitted
)

async def main() -> None:
completion = await client.chat.completions.create(
messages=[
{
"content": "create a poem using palindromes",
"role": "user",
}
],
model="gpt-oss-120b",
)

asyncio.run(main())

Functionality between the synchronous and asynchronous clients is otherwise identical.

With aiohttp

By default, the async client uses httpx for HTTP requests. However, for improved concurrency performance you may also use aiohttp as the HTTP backend.

You can enable this by installing aiohttp:

# install from PyPI
pip install sambanova[aiohttp]

Then you can enable it by instantiating the client with http_client=DefaultAioHttpClient():

import os
import asyncio
from sambanova import DefaultAioHttpClient
from sambanova import AsyncSambaNova

async def main() -> None:
async with AsyncSambaNova(
api_key=os.environ.get("SAMBANOVA_API_KEY"), # This is the default and can be omitted
http_client=DefaultAioHttpClient(),
) as client:
completion = await client.chat.completions.create(
messages=[
{
"content": "create a poem using palindromes",
"role": "user",
}
],
model="gpt-oss-120b",
)

asyncio.run(main())

Streaming responses

We provide support for streaming responses using Server Side Events (SSE).

from sambanova import SambaNova

client = SambaNova()

stream = client.chat.completions.create(
messages=[
{
"content": "create a poem using palindromes",
"role": "user",
}
],
model="gpt-oss-120b",
stream=True,
)
for completion in stream:
print(completion)

The async client uses the exact same interface.

from sambanova import AsyncSambaNova

client = AsyncSambaNova()

stream = await client.chat.completions.create(
messages=[
{
"content": "create a poem using palindromes",
"role": "user",
}
],
model="gpt-oss-120b",
stream=True,
)
async for completion in stream:
print(completion)

Using types

Nested request parameters are TypedDicts. Responses are Pydantic models which also provide helper methods for things like:

• Serializing back into JSON, model.to_json()
• Converting to a dictionary, model.to_dict()

Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set python.analysis.typeCheckingMode to basic.

Nested params

Nested parameters are dictionaries, typed using TypedDict, for example:

from sambanova import SambaNova

client = SambaNova()

completion = client.chat.completions.create(
messages=[
{
"content": "create a poem using palindromes",
"role": "user",
}
],
model="gpt-oss-120b",
chat_template_kwargs={"enable_thinking": True},
)
print(completion.chat_template_kwargs)

File uploads

Request parameters that correspond to file uploads can be passed as bytes, or a `PathLike` instance or a tuple of (filename, contents, media type).

from pathlib import Path
from sambanova import SambaNova

client = SambaNova()

client.audio.transcriptions.create(
file=Path("/path/to/file"),
model="Whisper-Large-v3",
)

The async client uses the exact same interface. If you pass a `PathLike` instance, the file contents will be read asynchronously automatically.

Handling errors

When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of sambanova.APIConnectionError is raised.

When the API returns a non-success status code (that is, 4xx or 5xx response), a subclass of sambanova.APIStatusError is raised, containing status_code and response properties.

All errors inherit from sambanova.APIError.

import sambanova
from sambanova import SambaNova

client = SambaNova()

try:
client.chat.completions.create(
messages=[
{
"content": "create a poem using palindromes",
"role": "user",
}
],
model="gpt-oss-120b",
)
except sambanova.APIConnectionError as e:
print("The server could not be reached")
print(e.__cause__) # an underlying Exception, likely raised within httpx.
except sambanova.RateLimitError as e:
print("A 429 status code was received; we should back off a bit.")
except sambanova.APIStatusError as e:
print("Another…