OpenAI API client for Kotlin

Kotlin client for OpenAI's API with multiplatform and coroutines capabilities.

📦 Setup

1. Install OpenAI API Kotlin client by adding the following dependency to your build.gradle file:

repositories {
    mavenCentral()
}

dependencies {
    implementation "com.aallam.openai:openai-client:4.1.0"
}

1. Choose and add to your dependencies one of Ktor's engines.

BOM

Alternatively, you can use openai-client-bom by adding the following dependency to your build.gradle file

dependencies {
    // import Kotlin API client BOM
    implementation platform('com.aallam.openai:openai-client-bom:4.1.0')

    // define dependencies without versions
    implementation 'com.aallam.openai:openai-client'
    runtimeOnly 'io.ktor:ktor-client-okhttp'
}

Multiplatform

In multiplatform projects, add openai client dependency to commonMain, and choose an engine for each target.

Maven

Gradle is required for multiplatform support, but there's nothing stopping you from using the jvm client in a Maven project. You still need to add to your dependencies one of Ktor's engines.

<dependencies>
    <dependency>
        <groupId>com.aallam.openai</groupId>
        <artifactId>openai-client-jvm</artifactId>
        <version>4.1.0</version>
    </dependency>

    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-client-okhttp-jvm</artifactId>
        <version>3.0.0</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

The BOM is not supported for Maven projects.

⚡️ Getting Started

[!NOTE] OpenAI encourages using environment variables for the API key. Read more.

Create an instance of OpenAI client:

val openai = OpenAI(
    token = "your-api-key",
    timeout = Timeout(socket = 60.seconds),
    // additional configurations...
)

Or you can create an instance of OpenAI using a pre-configured OpenAIConfig:

val config = OpenAIConfig(
    token = apiKey,
    timeout = Timeout(socket = 60.seconds),
    // additional configurations...
)

val openAI = OpenAI(config)

Use your OpenAI instance to make API requests. Learn more.

Supported features

• Responses
• Models
• Chat
• Images
• Embeddings
• Files
• Fine-tuning
• Moderations
• Audio
• Batch

Beta

• Assistants
• Threads
• Messages
• Runs
• Vector Stores

Deprecated

• Completions
• Fine-tunes
• Edits

Looking for a tokenizer? Try ktoken, a Kotlin library for tokenizing text.

📚 Guides

Get started and understand more about how to use OpenAI API client for Kotlin with these guides:

• Getting Started
• Chat & Tool Calls
• FileSource Guide
• Assistants

ℹ️ Sample apps

Sample apps are available under sample, please check the README for running instructions.

🔒 ProGuard / R8

The specific rules are already bundled into the Jar which can be interpreted by R8 automatically.

📸 Snapshots

To import snapshot versions into your project, add the following code snippet to your gradle file:

repositories {
   //...
   maven { url 'https://central.sonatype.com/repository/maven-snapshots/' }
}

🛠️ Troubleshooting

For common issues and their solutions, check the Troubleshooting Guide.

🧪 Testing

openai-client tests are live integration tests and can generate billable API traffic.

• Default (non-billable): live tests are disabled.
• Opt-in live tests: set OPENAI_LIVE_TESTS=1 and OPENAI_API_KEY.

Examples:

# Free/offline checks
./gradlew :openai-core:jvmTest :openai-core:jsTest :openai-core:wasmJsTest :openai-core:apiCheck :openai-client:apiCheck

# Live smoke (billable)
OPENAI_LIVE_TESTS=1 OPENAI_API_KEY=... ./gradlew :openai-client:jvmTest --tests "*.TestModels"

⭐️ Support

Appreciate the project? Here's how you can help:

1. Star: Give it a star at the top right. It means a lot!
2. Contribute: Found an issue or have a feature idea? Submit a PR.
3. Feedback: Have suggestions? Open an issue or start a discussion.

📄 License

OpenAI Kotlin API Client is an open-sourced software licensed under the MIT license. This is an unofficial library, it is not affiliated with nor endorsed by OpenAI. Contributions are welcome.