Go SDK: AI Gateway chat

Call the Square Cloud AI Gateway from the Go SDK (sdk-api-go) with c.AI.Chat: OpenAI-compatible chat completions, without streaming.

c.AI.Chat(ctx, request) calls the AI Gateway, an OpenAI-compatible chat completions endpoint. It needs the ai:chat scope and a Standard plan or above.

The shorter snippets below run inside the program from Running the examples: paste one at a time into main and run goimports.

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

func main() {
	ctx := context.Background()
	c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))

	completion, err := c.AI.Chat(ctx, squarecloud.ChatRequest{
		Model: "cubic",
		Messages: []squarecloud.ChatMessage{
			{Role: "system", Content: "You are a helpful assistant."},
			{Role: "user", Content: "What is Square Cloud?"},
		},
		MaxTokens: 512,
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(completion.Choices[0].Message.Content)
	fmt.Println(completion.Usage.TotalTokens)
}

Request

squarecloud.ChatRequest fields, with their JSON names:

Field	Description
Model (model)	cubic. Accepted for compatibility: there is no other model. "" is not sent
Messages (messages)	[]ChatMessage with Role, Content, ToolCallID (tool_call_id) and ToolCalls (tool_calls). Role is system, user, assistant or tool. Content is always sent, "" included
Tools / ToolChoice (tools / tool_choice)	OpenAI function calling: Tools is a []json.RawMessage, ToolChoice any JSON-encodable value
MaxTokens (max_tokens)	Maximum tokens of the answer. 0 is not sent
Temperature (temperature)	Sampling temperature, a *float64. nil is not sent

The response is a ChatCompletion with the OpenAI shape: ID, Object, Created, Model, Choices (Index, Message, FinishReason) and Usage (PromptTokens, CompletionTokens, TotalTokens).

No streaming

AI.Chat does not stream: it returns the whole completion. ChatRequest has no stream field; the API answers 400 stream_not_supported to stream: true.

Timeout

The gateway gives each request 90 seconds in total, then answers 503 server_overloaded. Without a ctx deadline, the SDK waits at least 2 minutes before timing out, so you get the gateway’s answer.

Errors

AI errors use the OpenAI format, so their codes are lowercase. They are still returned as an *APIError, with Code set to the OpenAI code (or its type when there is no code):

_, err := c.AI.Chat(ctx, squarecloud.ChatRequest{
	Messages: []squarecloud.ChatMessage{{Role: "user", Content: "Hi"}},
})

var apiErr *squarecloud.APIError
if errors.As(err, &apiErr) && apiErr.Code == "server_overloaded" {
	// safe to retry yourself
}

Status	Code	When
400	stream_not_supported	stream: true was sent
400	invalid_messages, invalid_tools, invalid_tool_choice, invalid_temperature, invalid_max_tokens	A malformed field
400	context_length_exceeded	The conversation exceeds the plan’s context window
401	access_denied	Invalid API key
403	upgrade_required	The plan has no AI Gateway access
429	rate_limit_exceeded, concurrent_limit_reached	Too fast, or a request already in flight
429	daily_limit_reached, daily_request_limit_reached, daily_spend_limit_reached	A daily budget is used up (resets at 00:00 UTC)
503	server_overloaded	Capacity is full or the 90 s deadline passed: safe to retry
503	daily_capacity_reached	The platform’s daily capacity is used up

The SDK never retries AI errors: the request is a non-idempotent POST. See the AI Gateway reference for plan limits.

Next steps

Errors

Error class, retries and rate limits.

AI Gateway reference

Models, plan limits and the OpenAI-compatible endpoint.