Skip to content

Latest commit

 

History

History
851 lines (627 loc) · 18.2 KB

GettingStarted.md

File metadata and controls

851 lines (627 loc) · 18.2 KB
Raw

Getting Started

Create an instance of OpenAI client:

val openAI = OpenAI(apiKey)

ℹ️ OpenAI encourages using environment variables for the API key. Read more.

Use your OpenAI instance to make API requests.

Beta

Deprecated

Models

List and describe the various models available in the API. You can refer to the Models documentation to understand what models are available and the differences between them.

List models

Lists the currently available models, and provides basic information about each one such as the owner and availability.

val models: List<Model> = openAI.models()

Retrieve a model

Retrieves a model instance, providing basic information about the model such as the owner and permissioning.

val id = ModelId("text-ada-001")
val model: Model = openAI.model(id)

Chat

Given a chat conversation, the model will return a chat completion response.

Create chat completion

Creates a completion for the chat message.

val chatCompletionRequest = ChatCompletionRequest(
    model = ModelId("gpt-3.5-turbo"),
    messages = listOf(
        ChatMessage(
            role = ChatRole.System,
            content = "You are a helpful assistant!"
        ),
        ChatMessage(
            role = ChatRole.User,
            content = "Hello!"
        )
    )
)
val completion: ChatCompletion = openAI.chatCompletion(chatCompletionRequest)
// or, as flow
val completions: Flow<ChatCompletionChunk> = openAI.chatCompletions(chatCompletionRequest)

Images

Given a prompt and/or an input image, the model will generate a new image.

Create image

Creates an image given a prompt.

val images = openAI.imageURL( // or openAI.imageJSON
    creation = ImageCreation(
        prompt = "A cute baby sea otter",
        model = ModelId("dall-e-3"),
        n = 2,
        size = ImageSize.is1024x1024
    )
)

Edit images

Creates an edited or extended image given an original image and a prompt.

val images = openAI.imageURL( // or openAI.imageJSON
    edit = ImageEdit(
        image = FileSource(name = "<filename>", source = imageSource),
        model = ModelId("dall-e-2"),
        mask = FileSource(name = "<filename>", source = maskSource),
        prompt = "a sunlit indoor lounge area with a pool containing a flamingo",
        n = 1,
        size = ImageSize.is1024x1024
    )
)

Create image variation

Creates a variation of a given image.

val images = openAI.imageURL( // or openAI.imageJSON
    variation = ImageVariation(
        image = FileSource(name = "<filename>", source = imageSource),
        model = ModelId("dall-e-3"),
        n = 1,
        size = ImageSize.is1024x1024
    )
)

Embeddings

Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms.

Create embeddings

Creates an embedding vector representing the input text.

val embeddings = openAI.embeddings(
    request = EmbeddingRequest(
        model = ModelId("text-similarity-babbage-001"),
        input = listOf("The food was delicious and the waiter...")
    )
)

Fine-tuning

Manage fine-tuning jobs to tailor a model to your specific training data.

Create fine-tuning job

Creates a job that fine-tunes a specified model from a given dataset.

Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete.

No Hyperparameters

val request = FineTuningRequest(
    trainingFile = FileId("file-abc123"),
    model = ModelId("gpt-3.5-turbo"),
)
val fineTuningJob = client.fineTuningJob(request)

Hyperparameters

val request = FineTuningRequest(
    trainingFile = FileId("file-abc123"),
    model = ModelId("gpt-3.5-turbo"),
    hyperparameters = Hyperparameters(nEpochs = 2),
)
val fineTuningJob = client.fineTuningJob(request)

Validation File

val request = FineTuningRequest(
    trainingFile = FileId("file-abc123"),
    validation_file = FileId("file-def345"),
    model = ModelId("gpt-3.5-turbo"),
)
val fineTuningJob = client.fineTuningJob(request)

List fine-tuning jobs

List your organization's fine-tuning jobs

val fineTuningJobs = client.fineTuningJobs(limit = 2)

Retrieve fine-tuning job

Get info about a fine-tuning job.

val id = FineTuningId("ft-AF1WoRqd3aJAHsqc9NY7iL8F")
val fineTuningJob = client.fineTuningJob(id)

Cancel fine-tuning

Immediately cancel a fine-tune job.

val id = FineTuningId("ftjob-abc12")
client.cancel(id)

List fine-tuning events

Get status updates for a fine-tuning job.

val id = FineTuningId("ftjob-abc12")
val fineTuningEvents = client.fineTuningEvents(id)

Audio

Learn how to turn audio into text.

Create speech

Generates audio from the input text.

val rawAudio = openAI.speech(
  request = SpeechRequest(
    model = ModelId("tts-1"),
    input = "The quick brown fox jumped over the lazy dog.",
    voice = Voice.Alloy,
  )
)

Create transcription

Transcribes audio into the input language.

val request = TranscriptionRequest(
    audio = FileSource(name = "<filename>", source = audioSource),
    model = ModelId("whisper-1"),
)
val transcription = openAI.transcription(request)

Create translation

Translates audio into English.

val request = TranslationRequest(
    audio = FileSource(name = "<filename>", source = audioSource),
    model = ModelId("whisper-1"),
)
val translation = openAI.translation(request)

Files

Files are used to upload documents that can be used with features like Fine-tuning.

List files

Returns a list of files that belong to the user's organization.

val files = openAI.files()

Upload file

Upload a file that contains document(s) to be used across various endpoints/features. Currently, the size of all the files uploaded by one organization can be up to 1 GB.

val file = openAI.file(
    request = FileUpload(
        file = source,
        purpose = Purpose("fine-tune")
    )
)

Delete file

Delete a file.

openAI.delete(fileId)

Retrieve file

Returns information about a specific file.

val file = openAI.file(fileId)

Retrieve file content

Returns the contents of the specified file

val bytes = openAI.download(fileId)

Moderations

Given an input text, outputs if the model classifies it as violating OpenAI's content policy.

Create moderation

Classifies if text violates OpenAI's Content Policy

val moderation = openAI.moderations(
    request = ModerationRequest(
        input = "I want to kill them."
    )
)

Hosts

This library has support for custom ChatGPT URLs. The host used by default is https://api.openai.com/v1/, as you would expect, and support for Azure hosted ChatGPT is built in as well.

Azure

To connect to an Azure hosted instance, use the OpenAIHost.azure function like so:

val host = OpenAIHost.azure(
    resourceName = "The name of your Azure OpenAI Resource.",
    deploymentId = "The name of your model deployment.",
    apiVersion = "The API version to use for this operation. This parameter should follow the YYYY-MM-DD format.",
)
val config = OpenAIConfig(
    host = host,
    token = "Your API token",
)
val openAI = OpenAI(config)

Other hosts

You can connect to whatever host you like by constructing your own OpenAIHost instance. Otherwise, it's exactly the same as the above Azure example.

val host = OpenAIHost(
    baseUrl = "http://localhost:8080",
)
val config = OpenAIConfig(
    host = host,
    token = "Your API token",
)
val openAI = OpenAI(config)

Completions

Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position.

Create Completion legacy

Creates a completion for the provided prompt and parameters

val completionRequest = CompletionRequest(
    model = ModelId("text-ada-001"),
    prompt = "Somebody once told me the world is gonna roll me",
    echo = true
)
val completion: TextCompletion = openAI.completion(completionRequest)
// or, as flow
val completions: Flow<TextCompletion> = openAI.completions(completionRequest)

Fine-tunes

Manage fine-tuning jobs to tailor a model to your specific training data.

Create fine-tune

Creates a job that fine-tunes a specified model from a given dataset.

Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete.

val fineTune = openAI.fineTune(
    request = FineTuneRequest(
        trainingFile = trainingFile,
        model = ModelId("ada")
    )
)

List fine-tunes

List your organization's fine-tuning jobs

val fineTunes = openAI.fineTunes()

Retrieve fine-tune

Gets info about the fine-tune job.

val finetune = openAI.fineTune(fineTune.id)

Cancel fine-tune

Immediately cancel a fine-tune job.

val finetune = openAI.cancel(fineTune.id)

List fine-tune events

Get fine-grained status updates for a fine-tune job.

val fineTuneEvents: List<FineTuneEvent> = openAI.fineTuneEvents(fineTune.id)
// or, as flow
val fineTuneEvents: Flow<FineTuneEvent> = openAI.fineTuneEventsFlow(fineTune.id)

Delete fine-tune model

Delete a fine-tuned model. You must have the Owner role in your organization.

openAI.delete(fileId)

Edits

Given a prompt and an instruction, the model will return an edited version of the prompt.

Create edits Deprecated

Creates a new edit for the provided input, instruction, and parameters.

val edit = openAI.edit(
    request = EditsRequest(
        model = ModelId("text-davinci-edit-001"),
        input = "What day of the wek is it?",
        instruction = "Fix the spelling mistakes"
    )
)

Assistants

Build assistants that can call models and use tools to perform tasks.

Create assistant

Create an assistant with a model and instructions.

val assistant = openAI.assistant(
  request = AssistantRequest(
    name = "Math Tutor",
    tools = listOf(AssistantTool.CodeInterpreter),
    model = ModelId("gpt-4")
  )
)

Retrieve assistant

Retrieves an assistant.

val assistant = openAI.assistant(id = AssistantId("asst_abc123"))

Modify assistant

Modifies an assistant.

val assistant = openAI.assistant(
    id = AssistantId("asst_abc123"), request = AssistantRequest(
        instructions = "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
        tools = listOf(AssistantTool.RetrievalTool),
        model = ModelId("gpt-4"),
        fileIds = listOf(FileId("file-abc123"), FileId("file-abc123")),
    )
)

Delete assistant

Delete an assistant.

openAI.delete(id = AssistantId("asst_abc123"))

List assistants

Returns a list of assistants.

val assistants = openAI.assistants()

Create assistant file

Create an assistant file by attaching a File to an assistant.

val assistant = openAI.createFile(
  assistantId = AssistantId("asst_abc123"),
  fileId = FileId("file_abc123")
)

Retrieve assistant file

Retrieve an assistant file.

val assistant = openAI.file(
  assistantId = AssistantId("asst_abc123"),
  fileId = FileId("file_abc123")
)

Delete assistant file

Delete an assistant file.

openAI.delete(
  assistantId = AssistantId("asst_abc123"),
  fileId = FileId("file_abc123")
)

List assistant files

Returns a list of assistant files.

val assistantFiles = openAI.files(assistantId = AssistantId("asst_abc123"))

Threads

Create threads that assistants can interact with.

Create thread

Create a thread with a prompt and instructions.

val thread = openAI.thread()

Retrieve thread

Retrieves a thread.

val thread = openAI.thread(id = ThreadId("thread_abc123"))

Modify thread

Modifies a thread.

val thread = openAI.thread(
  id = ThreadId("thread_abc123"),
  metadata = mapOf(
    "modified" to "true",
    "user" to "abc123"
  )
)

Delete thread

Delete a thread.

openAI.delete(id = ThreadId("thread_abc123"))

Messages

Create messages within threads

Create message

Create a message.

val message = openAI.message(
  threadId = ThreadId("thread_abc123"),
  request = MessageRequest(
    role = Role.User,
    content = "How does AI work? Explain it in simple terms.",
  )
)

Retrieve message

Retrieve a message.

val message = openAI.message(
  threadId = ThreadId("thread_abc123"),
  messageId = MessageId("message_abc123")
)

Modify message

Modifies a message.

val message = openAI.message(
  threadId = ThreadId("thread_abc123"),
  messageId = MessageId("message_abc123"),
  metadata = mapOf(
    "modified" to "true",
    "user" to "abc123"
  )
)

List messages

Returns a list of messages for a given thread.

val messages = openAI.messages(threadId = ThreadId("thread_abc123"))

Retrieve message file

A list of files attached to a Message.

val messageFile = openAI.messageFile(
  threadId = ThreadId("thread_abc123"),
  messageId = MessageId("message_abc123"),
  fileId = FileId("file_abc123")
)

List message files

Returns a list of message files.

val messageFiles = openAI.messageFiles(
  threadId = ThreadId("thread_abc123"),
  messageId = MessageId("message_abc123")
)

Runs

Represents an execution run on a thread.

Create run

Create a run.

val run = openAI.createRun(
  threadId = ThreadId("thread_abc123"),
  request = RunRequest(assistantId = AssistantId("assistant_abc123")),
)

Retrieve run

Retrieves a run.

val run = openAI.getRun(
  threadId = ThreadId("thread_abc123"),
  runId = RunId("run_abc123")
)

Modify run

Modifies a run.

val run = openAI.updateRun(
  threadId = ThreadId("thread_abc123"),
  runId = RunId("run_abc123"),
  metadata = mapOf("user_id" to "user_abc123")
)

List runs

Returns a list of runs belonging to a thread.

val runs = openAI.runs(threadId = ThreadId("thread_abc123"))

Cancel run

Cancel a run that is Status.InProgress

openAI.cancel(
  threadId = ThreadId("thread_abc123"),
  runId = RunId("run_abc123")
)

Create thread and run

Create a thread and run it in one request.

openAI.createThreadRun(
    request = ThreadRunRequest(
        assistantId = AssistantId("asst_abc123"),
        thread = ThreadRequest(
            messages = listOf(
                ThreadMessage(
                    role = Role.User,
                    content = "Explain deep learning to a 5 year old."
                )
            )
        ),
    )
)

Retrieve a run step

Retrieves a run step.

val runStep = openAI.runStep(
  threadId = ThreadId("thread_abc123"),
  runId = RunId("run_abc123"),
  stepId = RunStepId("step_abc123")
)

List run steps

Returns a list of run steps belonging to a run.

val runSteps = openAI.runSteps(
  threadId = ThreadId("thread_abc123"),
  runId = RunId("run_abc123")
)