Skip to main content

​
Overview

The Kelly AI SDK is built entirely on async/await syntax using aiohttp for HTTP requests. All API methods are asynchronous and must be awaited.

​
Basic usage

To use the SDK, you need to create an instance of KellyAPI and call its methods within an async function: 
import asyncio
from kellyapi import KellyAPI

async def main():
    api = KellyAPI(api_key="your_api_key_here")
    
    # Call async methods
    response = await api.llm(prompt="Hello, world!")
    print(response)

# Run the async function
asyncio.run(main())
All API methods in the SDK return coroutines that must be awaited. Forgetting to use await will return a coroutine object instead of the actual result.

​
Session management

The SDK automatically manages aiohttp.ClientSession instances. By default, a new session is created for each request: 
from kellyapi import KellyAPI

# Default behavior - new session per request
api = KellyAPI(api_key="your_api_key_here")
For better performance when making multiple requests, you can provide your own aiohttp.ClientSession: 
import aiohttp
from kellyapi import KellyAPI

async def main():
    # Create a session that will be reused
    async with aiohttp.ClientSession() as session:
        api = KellyAPI(
            api_key="your_api_key_here",
            session=lambda: session
        )
        
        # Make multiple requests with the same session
        response1 = await api.llm(prompt="First question")
        response2 = await api.llm(prompt="Second question")
        response3 = await api.generate(prompt="An image")
When passing a custom session, you must pass it as a callable (lambda or function) that returns the session object, not the session directly. See the example above.

​
Making multiple concurrent requests

You can use asyncio.gather() to make multiple API calls concurrently: 
import asyncio
from kellyapi import KellyAPI

async def main():
    api = KellyAPI(api_key="your_api_key_here")
    
    # Run multiple requests concurrently
    results = await asyncio.gather(
        api.llm(prompt="What is AI?"),
        api.llm(prompt="What is ML?"),
        api.llm(prompt="What is DL?")
    )
    
    for i, result in enumerate(results, 1):
        print(f"Response {i}: {result}")

asyncio.run(main())

​
Timeout configuration

The SDK uses a default timeout of 60 seconds for API requests. This is handled internally in the _fetch and _post_json methods: 
async def _fetch(self, route, timeout=60, **params):
    async with self.session() as client:
        resp = await client.get(
            self.api + route,
            params=params,
            headers={"Authorization": f"Bearer {self.api_key}"},
            timeout=timeout,
        )
The timeout is applied to all HTTP requests in the SDK. If a request exceeds the timeout, a TimeoutError will be raised. See the error handling guide for more information.From /home/daytona/workspace/source/kellyapi/api.py:31-53

​
Running in different contexts

import asyncio
from kellyapi import KellyAPI

async def main():
    api = KellyAPI(api_key="your_api_key_here")
    result = await api.llm(prompt="Hello!")
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

​
Best practices

All SDK methods are asynchronous and must be awaited. Never call them without await:
# ❌ Wrong - returns a coroutine object
result = api.llm(prompt="Hello")

# ✅ Correct - awaits the result
result = await api.llm(prompt="Hello")
Creating a new session for each request adds overhead. Reuse sessions when making multiple API calls:
async with aiohttp.ClientSession() as session:
    api = KellyAPI(api_key="key", session=lambda: session)
    # Make multiple requests...
Long-running operations like image generation may take time. Consider increasing timeouts or implementing retry logic for critical operations.
When you need results from multiple independent API calls, use asyncio.gather() to run them concurrently rather than sequentially.

​
Next steps

Error handling

Learn how to handle errors and exceptions

Working with images

Handle image data with base64 encoding

Build docs developers (and LLMs) love

Get started for freeTalk to us