togethercomputer/together-go

togethercomputer/together-go

Description: Official Together AI Go library

Language: Go

License: Apache-2.0

Stars: 1

Forks: 0

Open issues: 3

Created: 2024-05-10T05:10:19Z

Pushed: 2026-06-10T13:20:56Z

Default branch: main

Fork: no

Archived: no

README:

Together Go API Library

The Together Go library provides convenient access to the Together REST API from applications written in Go.

It is generated with Stainless.

Installation

import (
"github.com/togethercomputer/together-go" // imported as together
)

Or to pin the version:

go get -u 'github.com/togethercomputer/together-go@v0.10.0'

Requirements

This library requires Go 1.22+.

Usage

The full API of this library can be found in [api.md](api.md).

package main

import (
"context"
"fmt"

"github.com/togethercomputer/together-go"
"github.com/togethercomputer/together-go/option"
)

func main() {
client := together.NewClient(
option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("TOGETHER_API_KEY")
)
chatCompletion, err := client.Chat.Completions.New(context.TODO(), together.ChatCompletionNewParams{
Messages: []together.ChatCompletionNewParamsMessageUnion{{
OfChatCompletionNewsMessageChatCompletionUserMessageParam: &together.ChatCompletionNewParamsMessageChatCompletionUserMessageParam{
Role: "user",
Content: together.ChatCompletionNewParamsMessageChatCompletionUserMessageParamContentUnion{
OfString: together.String("Say this is a test!"),
},
},
}},
Model: "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
})
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", chatCompletion.Choices)
}

Request fields

The together library uses the `omitzero` semantics from the Go 1.24+ encoding/json release for request fields.

Required primitive fields (int64, string, etc.) feature the tag \api:"required"\. These fields are always serialized, even their zero values.

Optional primitive types are wrapped in a param.Opt[T]. These fields can be set with the provided constructors, together.String(string), together.Int(int64), etc.

Any param.Opt[T], map, slice, struct or string enum uses the tag \json:"...,omitzero"\. Its zero value is considered omitted.

The param.IsOmitted(any) function can confirm the presence of any omitzero field.

p := together.ExampleParams{
ID: "id_xxx", // required property
Name: together.String("..."), // optional property

Point: together.Point{
X: 0, // required field will serialize as 0
Y: together.Int(1), // optional field will serialize as 1
// ... omitted non-required fields will not be serialized
},

Origin: together.Origin{}, // the zero value of [Origin] is considered omitted
}

To send null instead of a param.Opt[T], use param.Null[T](). To send null instead of a struct T, use param.NullStruct[T]().

p.Name = param.Null[string]() // 'null' instead of string
p.Point = param.NullStruct[Point]() // 'null' instead of struct

param.IsNull(p.Name) // true
param.IsNull(p.Point) // true

Request structs contain a .SetExtraFields(map[string]any) method which can send non-conforming fields in the request body. Extra fields overwrite any struct fields with a matching key. For security reasons, only use SetExtraFields with trusted data.

To send a custom value instead of a struct, use param.Override[T](value).

// In cases where the API specifies a given type,
// but you want to send something else, use [SetExtraFields]:
p.SetExtraFields(map[string]any{
"x": 0.01, // send "x" as a float instead of int
})

// Send a number instead of an object
custom := param.Override[together.FooParams](12)

Request unions

Unions are represented as a struct with fields prefixed by "Of" for each of its variants, only one field can be non-zero. The non-zero field will be serialized.

Sub-properties of the union can be accessed via methods on the union struct. These methods return a mutable pointer to the underlying data, if present.

// Only one field can be non-zero, use param.IsOmitted() to check if a field is set
type AnimalUnionParam struct {
OfCat *Cat `json:",omitzero,inline`
OfDog *Dog `json:",omitzero,inline`
}

animal := AnimalUnionParam{
OfCat: &Cat{
Name: "Whiskers",
Owner: PersonParam{
Address: AddressParam{Street: "3333 Coyote Hill Rd", Zip: 0},
},
},
}

// Mutating a field
if address := animal.GetOwner().GetAddress(); address != nil {
address.ZipCode = 94304
}

Response objects

All fields in response structs are ordinary value types (not pointers or wrappers). Response structs also include a special JSON field containing metadata about each property.

type Animal struct {
Name string `json:"name,nullable"`
Owners int `json:"owners"`
Age int `json:"age"`
JSON struct {
Name respjson.Field
Owner respjson.Field
Age respjson.Field
ExtraFields map[string]respjson.Field
} `json:"-"`
}

To handle optional data, use the .Valid() method on the JSON field. .Valid() returns true if a field is not null, not present, or couldn't be marshaled.

If .Valid() is false, the corresponding field will simply be its zero value.

raw := `{"owners": 1, "name": null}`

var res Animal
json.Unmarshal([]byte(raw), &res)

// Accessing regular fields

res.Owners // 1
res.Name // ""
res.Age // 0

// Optional field checks

res.JSON.Owners.Valid() // true
res.JSON.Name.Valid() // false
res.JSON.Age.Valid() // false

// Raw JSON values

res.JSON.Owners.Raw() // "1"
res.JSON.Name.Raw() == "null" // true
res.JSON.Name.Raw() == respjson.Null // true
res.JSON.Age.Raw() == "" // true
res.JSON.Age.Raw() == respjson.Omitted // true

These .JSON structs also include an ExtraFields map containing any properties in the json response that were not specified in the struct. This can be useful for API features not yet present in the SDK.

body := res.JSON.ExtraFields["my_unexpected_field"].Raw()

Response Unions

In responses, unions are represented by a flattened struct containing all possible fields from each of the object variants. To convert it to a variant use the .AsFooVariant() method or the .AsAny() method if present.

If a response value union contains primitive values, primitive fields will be alongside the properties but prefixed with Of and feature the tag json:"...,inline".

type AnimalUnion struct {
// From variants…