imaxmelnyk / openai-scala   0.3.0

MIT License GitHub

OpenAI Scala Client

Scala versions: 3.x 2.13 2.12

OpenAI Scala Client

The OpenAI Scala Client is a library that provides a Scala interface to the OpenAI API, allowing you to programmatically interact with OpenAI's artificial intelligence models. The library uses cats for generic monads and sttp for http client abstraction.


Currently supported Scala versions are 2.12, 2.13 and 3.
To install the OpenAI Scala Client, add the following dependency to your project's build.sbt file:

"dev.maxmelnyk" %% "openai-scala" % "0.3.0"

Getting Started

Before using the OpenAI Scala Client, you will need to obtain an OpenAI API key and (optionally) an organization ID as described in the OpenAI API documentation. Once you have obtained your API key and organization ID, you can specify them using environment variables. Set the OPENAI_API_KEY and (optionally) OPENAI_ORG_ID environment variables to your API key and organization ID respectively.
Alternatively, you can explicitly specify your API key and organization ID when creating a new OpenAI client object. See the example below:

import dev.maxmelnyk.openaiscala.client.OpenAIClient

// with organization id
val client = OpenAIClient("<your-api-key>", Some("<your-org-id>"))(sttpBackend)

// without organization id
val client = OpenAIClient("<your-api-key>")(sttpBackend)

// api key and org id taken from env vars
val client = OpenAIClient(sttpBackend)

In the following sections, we assume that the OPENAI_API_KEY and (optionally) OPENAI_ORG_ID environment variables have been set up correctly.


Using the OpenAI Scala Client is straightforward if you're already using sttp in your project and have a sttpBackend set up. Here's an example:

import dev.maxmelnyk.openaiscala.client.OpenAIClient

val sttpBackend = ???

val client = OpenAIClient(sttpBackend)

Please note that the cats's MonadThrow[F] for the monad F used in sttpBackend must be implicitly in scope.


As a simple example lets use cats effect IO monad and http4s as sttp backend.

First, make sure you have the following dependencies:

// cats effect
"org.typelevel" %% "cats-effect" % "<cats_effect_version>"

// http4s client
"org.http4s" %% "http4s-dsl" % "<http4s_version>"
"org.http4s" %% "http4s-blaze-client" % "<http4s_version>"

// sttp adapter for http4s
"com.softwaremill.sttp.client3" %% "http4s-backend" % "<sttp_version>"

Then, in your code:

import cats.effect.{IO, IOApp}
import dev.maxmelnyk.openaiscala.client.OpenAIClient
import dev.maxmelnyk.openaiscala.models.models.Models
import sttp.client3.http4s.Http4sBackend


object Main extends IOApp.Simple {
  val run: IO[Unit] = {
    val sttpBackendResource = Http4sBackend.usingDefaultBlazeClientBuilder[IO]()

    sttpBackendResource.use { sttpBackend =>
      val client = OpenAIClient(sttpBackend)

      for {
        // models api
        models <- client.listModels
        davinciModel <- client.retrieveModel(Models.davinci)

        // text apis
        completion <- client.createCompletion(Seq("This is a test."))
        chatCompletion <- client.createChatCompletion(Seq(ChatCompletion.Message(ChatCompletion.Message.Role.User, "Hello!")))
        edit <- client.createEdit("What day of the wek is it?", "Fix the spelling mistakes")

        // images api
        sourceImage = new File("/path/to/file/image.png")
        mask = new File("/path/to/file/mask.png")

        image <- client.createImage("A cute baby sea otter")
        editedImage <- client.createImageEdit(sourceImage, Some(mask), "A cute baby sea otter wearing a beret")
        variedImage <- client.createImageVariation(sourceImage)
      } yield {

Please note that this is just an example, and you can use any compatible monad and sttp backend with the OpenAI Scala Client.
This example can be found here, more examples can be found in the examples directory.


This project is licensed under the MIT License - see the LICENSE file for details.