SDK quickstart: Go

OpenAI's official Go SDK (openai-go) is the easiest path. The community go-openai library works too.

Install

go get github.com/openai/openai-go

Hello world

package main

import (
  "context"
  "fmt"
  "os"

  "github.com/openai/openai-go"
  "github.com/openai/openai-go/option"
)

func main() {
  client := openai.NewClient(
    option.WithBaseURL("https://api.greenjoules.cloud/v1/"),
    option.WithAPIKey(os.Getenv("JC_API_KEY")),
  )

  r, err := client.Chat.Completions.New(context.Background(),
    openai.ChatCompletionNewParams{
      Model: openai.F("auto"),
      Messages: openai.F([]openai.ChatCompletionMessageParamUnion{
        openai.UserMessage("hi"),
      }),
    },
  )
  if err != nil {
    panic(err)
  }
  fmt.Println(r.Choices[0].Message.Content)
}

Joule headers

The SDK exposes the raw HTTP response on the parent struct:

resp, err := client.Chat.Completions.New(ctx, params)
if err != nil { return err }

raw := resp.RawResponse // *http.Response
fmt.Println("joules:", raw.Header.Get("X-Energy-Joules"))
fmt.Println("routed:", raw.Header.Get("X-Routed-To"))
fmt.Println("tier:", raw.Header.Get("X-Tier"))

Streaming

stream := client.Chat.Completions.NewStreaming(ctx, params)
defer stream.Close()
for stream.Next() {
  chunk := stream.Current()
  if len(chunk.Choices) > 0 {
    fmt.Print(chunk.Choices[0].Delta.Content)
  }
}
if err := stream.Err(); err != nil {
  return err
}

Embeddings + tool use

// embeddings
e, _ := client.Embeddings.New(ctx, openai.EmbeddingNewParams{
  Model: openai.F(openai.EmbeddingModelTextEmbedding3Small),
  Input: openai.F[openai.EmbeddingNewParamsInputUnion](
    openai.EmbeddingNewParamsInputArrayOfStrings([]string{"a", "b"}),
  ),
})

// tools
params := openai.ChatCompletionNewParams{
  Model: openai.F("auto"),
  Tools: openai.F([]openai.ChatCompletionToolParam{{
    Type: openai.F("function"),
    Function: openai.F(shared.FunctionDefinitionParam{
      Name: openai.F("get_weather"),
      Description: openai.F("Get current weather"),
      Parameters: openai.F(shared.FunctionParameters{
        "type": "object",
        "properties": map[string]any{"location": map[string]any{"type": "string"}},
      }),
    }),
  }}),
  Messages: openai.F([]openai.ChatCompletionMessageParamUnion{
    openai.UserMessage("weather in helsinki?"),
  }),
}

Errors

r, err := client.Chat.Completions.New(ctx, params)
if err != nil {
  var apierr *openai.Error
  if errors.As(err, &apierr) {
    switch apierr.StatusCode {
    case 402: // insufficient balance
    case 429: // energy budget hit
    }
  }
}

Next

For the object-store side, see the AWS S3 migration guide — aws-sdk-go-v2 works against our endpoint unchanged.