ai-openchat

A fully asynchronous Python client for the OpenAI API, built on aiohttp.

---

What is it?

ai-openchat is a small, dependency-light wrapper around the OpenAI HTTP API that runs entirely on asyncio. Instead of blocking your event loop with synchronous requests, every call is a coroutine you can await, making it a natural fit for async applications such as Discord/Telegram bots, FastAPI/aiohttp web services, and background workers.

It ships with a large catalogue of ready-made prompt presets (based on the official OpenAI examples) so you can get useful completions with a single line of code, while still allowing fully custom parameters when you need them.

Highlights

• 100% async — powered by aiohttp, no blocking calls.
• Text completions — the completions endpoint with 50+ built-in prompt presets.
• Image generation — the DALL·E image generations endpoint.
• Configurable client — override the base URL, request timeout, or route traffic through a SOCKS/HTTP proxy.
• Minimal dependencies — only aiohttp is required.

Installation

pip install ai-openchat

Requires Python 3.8+.

To use proxy support you also need aiohttp-socks:

pip install ai-openchat aiohttp-socks

Quickstart

The client reads your OpenAI API key from you directly. The examples below pull it from the OPENAI_API_KEY environment variable so you never hardcode secrets.

import os
import asyncio

from ai_openchat import AsyncOpenAI, Model


async def main():
    client = AsyncOpenAI(token=os.getenv("OPENAI_API_KEY"))
    response = await client.generate_message("Tell me a fun fact about the ocean.", Model().chat())
    print(response)


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

generate_message returns the raw JSON response from OpenAI as a Python dict, so you can read the generated text from response["choices"][0]["text"].

Usage

Public API

The package exposes three top-level objects:

Object	Import	Purpose
AsyncOpenAI	from ai_openchat import AsyncOpenAI	The async client. Instantiate with your API token.
Model	from ai_openchat import Model	Configuration for text completion requests, with prompt presets.
ImageModel	from ai_openchat import ImageModel	Configuration for image generation requests.

AsyncOpenAI provides two coroutines:

• await client.generate_message(prompt: str, model: Model) — text completion.
• await client.generate_image(prompt: str, model: ImageModel) — image generation.

Text completions with presets

Model comes with dozens of preset methods taken from the official OpenAI example gallery. Each preset returns a configured Model instance you can pass straight to the client. A few of the available presets:

chat(), qa(), movie_to_emoji(), grammar_correction(), keywords(), explain_code(), sql_translate(), recipe_creator(), essay_outline(), tweet_classifier(), interview_questions() — and many more (see ai_openchat/model.py).

import os
import asyncio

from ai_openchat import AsyncOpenAI, Model


async def movie_to_emoji():
    client = AsyncOpenAI(token=os.getenv("OPENAI_API_KEY"))
    response = await client.generate_message(
        "Convert movie titles into emoji.\n\n"
        "Back to the Future: 👨👴🚗🕒 \n"
        "Batman: 🤵🦇 \n"
        "Transformers: 🚗🤖 \n"
        "Star Wars:",
        Model().movie_to_emoji(),
    )
    print(response["choices"][0]["text"])


asyncio.run(movie_to_emoji())

Custom completion parameters

You can build a fully custom Model instead of using a preset:

import os
import asyncio

from ai_openchat import AsyncOpenAI, Model


async def custom_completion():
    model = Model(
        model="text-davinci-003",
        temperature=0.0,
        max_tokens=100,
        top_p=1.0,
        frequency_penalty=0.5,
        presence_penalty=0.0,
        stop=["\n"],
    )

    client = AsyncOpenAI(token=os.getenv("OPENAI_API_KEY"))
    response = await client.generate_message("Hello!", model)
    print(response)


asyncio.run(custom_completion())

Image generation

import os
import asyncio

from ai_openchat import AsyncOpenAI, ImageModel


async def generate_image():
    client = AsyncOpenAI(token=os.getenv("OPENAI_API_KEY"))
    response = await client.generate_image("Captain America", ImageModel().image())
    print(response["data"][0]["url"])


asyncio.run(generate_image())

You can also configure the image request directly:

custom_image = ImageModel(n=2, size="512x512")
response = await client.generate_image("A watercolor fox", custom_image)

Advanced: custom session, timeout and proxy

The client accepts an optional session. Use AiohttpSession to set a request timeout, point to a custom base URL, or route requests through a proxy.

import os
import asyncio

from ai_openchat import AsyncOpenAI, Model
from ai_openchat.aiiohttp import AiohttpSession
from ai_openchat.base_openai import OpenAiAPIServer


async def main():
    session = AiohttpSession(
        api=OpenAiAPIServer.from_base("https://api.openai.com/v1"),
        timeout=30.0,
        # proxy="socks5://user:[email protected]:1080",  # requires aiohttp-socks
    )
    client = AsyncOpenAI(token=os.getenv("OPENAI_API_KEY"), session=session)
    response = await client.generate_message("Ping", Model().chat())
    print(response)


asyncio.run(main())

Examples

Runnable scripts live in the examples/ directory. They all read the API key from the OPENAI_API_KEY environment variable:

export OPENAI_API_KEY="sk-your-key-here"
python examples/chat.py
python examples/movie_to_emoji.py
python examples/generate_image.py

Notes

• This library targets OpenAI's completions and image generations endpoints.
• Responses are returned exactly as OpenAI sends them (parsed JSON), giving you full access to metadata such as usage and choices.
• Browse the full preset catalogue in ai_openchat/model.py and the OpenAI examples gallery at https://platform.openai.com/examples.

Technologies

• Python >= 3.8
• aiohttp >= 3.8

Contributing

Issues and pull requests are welcome. Please open an issue on the tracker to discuss substantial changes.

License

Distributed under the MIT License. See LICENSE for details.