Responses EN

Responses

English | 简体中文

---

SystemOne returns a *SystemOneResponse:

response.Model             // the model that answered; may differ from the requested alias
response.Usage             // Usage{InputTokens, OutputTokens *int} — nullable token counts
response.Answers           // map[string]Answer, keyed by question name
response.Nouls()           // map[string]*NoulAnswer
response.Choices()         // map[string]*ChoiceAnswer
response.Scores()          // map[string]*ScoreAnswer
response.Boxes()           // map[string]*BoxAnswer
response.RawRequestID()    // x-typesafe-request-id, or ""
response.RequestID()       // (string, error) — errors when the header is absent
response.RawBody()         // the payload exactly as received
response.RawHTTPResponse() // (*http.Response, error)

---

Answer Structures

Answers carry the primitive's structured data:

Type	Fields	Description
NoulAnswer	Type, Noul float64	Noul is a probability in [0, 1]
ChoiceAnswer	Type, Choice string, Confidence float64, Probabilities map[string]float64	Choice is the selected label
ScoreAnswer	Type, Score float64, Confidence float64, Legend map[int]any, Probabilities map[int]float64	Score is the weighted expectation across levels
BoxAnswer	Type, Box BoxCoordinates, Confidence *float64	Box holds normalized coordinates Top, Bottom, Left, Right

Box Coordinates (BoxCoordinates)

Each edge in BoxCoordinates represents a fraction of the total image dimensions, in [0, 1]:

type BoxCoordinates struct {
	Top    float64 `json:"top"`    // distance from top edge as fraction of height
	Bottom float64 `json:"bottom"` // distance from top edge as fraction of height
	Left   float64 `json:"left"`   // distance from left edge as fraction of width
	Right  float64 `json:"right"`  // distance from left edge as fraction of width
}

Nullable Token Counts (Usage)

In certain multimodal or evaluation modes, token counts may be omitted by the server. The fields in Usage are therefore pointers:

type Usage struct {
	InputTokens  *int `json:"input_tokens"`
	OutputTokens *int `json:"output_tokens"`
}

Usage implements fmt.Stringer, handling nil pointers cleanly:

fmt.Println(response.Usage)
// Prints: Usage{input_tokens: 492, output_tokens: 72}
// Or if null: Usage{input_tokens: null, output_tokens: null}

---

Grouped Accessors

Answers holds every answer as a typesafe.Answer interface. The four typed accessors (Nouls(), Choices(), Scores(), Boxes()) narrow answers by kind and return pointers to the exact same underlying structs:

response.Answers["queue"] == response.Choices()["queue"] // same pointer

---

Decoding Rules

• model and usage are required. A success response missing either — or holding a field of the wrong shape, including an explicit null where not allowed — is reported as an *APIResponseValidationError naming the dotted field path, such as answers.tone.confidence.
• answers is optional and defaults to empty.
• An answer whose type is not recognized is dropped from Answers and the grouped accessors, so newer server capabilities do not break existing SDK clients. It stays accessible via RawBody(), and the SDK logs a warning naming it.
• client.Models.List(ctx) returns a *ListModelsResponse; every field of every model (name, description, release_date) is required.

A malformed response is never silently coerced into a plausible zero value: a missing probability or a null where a number belongs always surfaces as an explicit error.

_, err := client.SystemOne(ctx, state, questions)
var validation *typesafe.APIResponseValidationError
if errors.As(err, &validation) {
	log.Printf("bad field: %s", validation.FieldPath)
}

---

HTTP Metadata

requestID := response.RawRequestID()            // "" when the header is absent
requestID, err = response.RequestID()          // error instead of ""

raw, err := response.RawHTTPResponse()         // status, headers, and the originating request
body := response.RawBody()                     // exactly what the server sent

MarshalJSON encodes only the API payload — model, usage, and answers — so HTTP metadata never leaks into a serialized response.