openai-kotlin

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.2.0"
}

2. 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.2.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.2.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
• Decisions
• Conversations
• Models
• Chat
• Images
• Embeddings
• Files
• Multipart uploads
• Fine-tuning
• Moderations
• Audio
• Realtime
• Batch
• Vector Stores
• Webhooks
• Organization usage and costs
• OrganizationAdministration
• Organization governance
• Containers
• Skills
• Voice management
• Live
• Spend controls
• Safety and content provenance
• Fine-tuning operations

Retired upstream APIs

The following interfaces remain available for existing consumers, but their OpenAI endpoints have shut down. See the migration guide.

• Assistants
• Threads
• Messages
• Runs
• Fine-tunes
• Edits

Vector Stores remain independent of the retired Assistants endpoints.

Legacy

• Completions is a legacy API; model availability is separate from endpoint support.

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
• API migration
• Archived Assistants guide

ℹ️ 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.

The JVM live suite excludes mocked offline fixtures. CI runs those once in Offline Checks, then runs the live suite plus the separate Live and Content Provenance tasks. Containers live tests remain opt-in for eligible projects.

Examples:

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

# Mocked HTTP client tests (no credentials or API traffic)
./gradlew :openai-client:offlineJvmTest

# 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.