ballerinax/openai.chat Ballerina library

Overview

OpenAI offers powerful AI models for tasks like natural language processing, audio transcription, and image generation.

The OpenAI Chat connector offers APIs to connect and interact with the chat completion related endpoints of the OpenAI REST API, enabling seamless interaction with advanced GPT models for diverse conversational and text generation tasks.

Key Features

• Integration with advanced GPT models including GPT-4o, GPT-4, and GPT-3.5
• Support for structured chat completions and interactive dialogues
• Efficient handling of conversational history and message roles
• Secure communication with API key-based authentication
• Simplified management of complex model parameters and response streams

Setup guide

To use the OpenAI Connector, you must have access to the OpenAI API through an OpenAI Platform account and a project under it. If you do not have a OpenAI Platform account, you can sign up for one here.

Create a OpenAI API Key

1. Open the OpenAI Platform Dashboard.

2. Navigate to Dashboard -> API keys.

   

3. Click on the "Create new secret key" button.

   

4. Fill the details and click on Create secret key.

   

5. Store the API key securely to use in your application.

   

Quickstart

To use the OpenAI Chat connector in your Ballerina application, update the .bal file as follows:

Step 1: Import the module

Import the ballerinax/openai.chat module.

import ballerinax/openai.chat;

Step 2: Create a new connector instance

Create a chat:Client with the obtained API Key and initialize the connector.

configurable string token = ?;

final chat:Client openAIChat = check new ({
    auth: {
        token
    }
});

Step 3: Invoke the connector operation

Now, you can utilize the available connector operation.

Create a chat completion

public function main() returns error? {
    chat:CreateChatCompletionRequest request = {
        model: "gpt-4o-mini",
        messages: [
            {
                "role": "user",
                "content": "What is Ballerina programming language?"
            }
        ]
    };

    chat:CreateChatCompletionResponse response =
        check openAIChat->/chat/completions.post(request);
}

Create a chat completion with a GPT-5 or other reasoning model

GPT-5 and the o-series models do not accept the deprecated max_tokens field. Use max_completion_tokens instead, which bounds the reasoning tokens and the visible completion tokens together. These models additionally accept reasoning_effort and verbosity, and they take instructions through a developer message rather than a system message.

public function main() returns error? {
    chat:CreateChatCompletionRequest request = {
        model: "gpt-5-mini",
        messages: [
            {
                "role": "developer",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "What is Ballerina programming language?"
            }
        ],
        max_completion_tokens: 2048,
        reasoning_effort: "low",
        verbosity: "low"
    };

    chat:CreateChatCompletionResponse response =
        check openAIChat->/chat/completions.post(request);
}

Note: Reasoning tokens are billed as completion tokens and are reported separately in response.usage.completion_tokens_details.reasoning_tokens. Setting max_completion_tokens too low can exhaust the budget on reasoning alone, returning an empty message with finish_reason set to "length".

Step 4: Run the Ballerina application

bal run

Examples

The OpenAI Chat connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

1. CLI assistant - Execute the user's task description by generating and running the appropriate command in the command line interface of their selected operating system.
2. Image to markdown document converter - Generate detailed markdown documentation based on the image content.