TitanGPT Python SDK

The official sync and async Python SDK for the OpenAI-compatible TitanGPT API.

• Python 3.8+
• Synchronous and asynchronous clients
• Responses accessible as dictionaries or through attributes
• Typed API exceptions with request IDs and OpenAI-compatible error metadata
• Automatic retries for retryable idempotent requests

Installation

python -m pip install --upgrade titangpt

Set your API key in the environment:

export TITANGPT_API_KEY="YOUR_API_KEY"

PowerShell:

$env:TITANGPT_API_KEY = "YOUR_API_KEY"

You can also pass api_key directly to either client.

Quick start

Synchronous client

from titangpt import TitanGPT


with TitanGPT() as client:
    response = client.chat.completions.create(
        model="gpt-5.6-terra",
        messages=[
            {"role": "user", "content": "Write a haiku about Python."},
        ],
    )

print(response.choices[0].message.content)

TitanResponse behaves like a normal dictionary, so the same value is also available as response["choices"][0]["message"]["content"].

Asynchronous client

import asyncio

from titangpt import AsyncTitanGPT


async def main() -> None:
    async with AsyncTitanGPT() as client:
        response = await client.chat.completions.create(
            model="gpt-5.6-terra",
            messages=[{"role": "user", "content": "Explain async I/O briefly."}],
        )
        print(response.choices[0].message.content)


asyncio.run(main())

Configuration

from titangpt import TitanGPT


client = TitanGPT(
    api_key="YOUR_API_KEY",             # or TITANGPT_API_KEY
    base_url="https://api.titangpt.xyz",
    timeout=60,
    max_retries=3,
    user_id="12345",
)

max_retries applies to retryable GET, HEAD, and OPTIONS requests. The client retries HTTP 429, 500, 502, 503, and 504 responses with bounded exponential backoff.

Error handling

HTTP and transport failures are exposed as typed exceptions:

from titangpt import (
    AuthenticationError,
    ModelNotFoundError,
    RateLimitError,
    TitanGPT,
    TitanGPTException,
)


try:
    with TitanGPT() as client:
        client.chat.completions.create(
            model="unknown-model",
            messages=[{"role": "user", "content": "Hello"}],
        )
except ModelNotFoundError as exc:
    print(exc.message)
    print(exc.code)        # model_not_found
    print(exc.request_id)  # include this when contacting support
except (AuthenticationError, RateLimitError) as exc:
    print(exc.status_code, exc.message)
except TitanGPTException as exc:
    print(f"TitanGPT request failed: {exc}")

API exceptions expose these diagnostic attributes:

Available exception classes include AuthenticationError, AuthorizationError, ValidationError, RateLimitError, ModelNotFoundError, NotFoundError, TimeoutError, ConnectionError, DataError, and APIError. All inherit from TitanGPTException.

API areas

The SDK currently provides:

• client.chat.completions
• client.models.list()
• client.files
• client.threads
• client.usage
• client.audio.transcriptions
• client.music.youtube
• client.music.yandex

The async client exposes the same areas with awaitable methods.

Development

python -m pip install -e ".[dev]"
python -m unittest discover -s tests -v
python -m build
python -m twine check --strict dist/*

See the changelog for release notes.

Links

• Website
• Documentation
• API status
• Issue tracker
• Telegram

License

MIT