Configuration EN

Configuration

English | 简体中文

---

Client Options

Explicit options take precedence over environment variables, which win over SDK defaults. Blank or whitespace-only environment variables are treated as unset.

client, err := typesafe.NewClient(
	typesafe.WithAPIKey("ts_live_..."),
	typesafe.WithBaseURL("https://api.typesafe.ai"),
	typesafe.WithDefaultModel("jev-latest"),
	typesafe.WithTimeout(15*time.Second),
	typesafe.WithRetryPolicy(typesafe.DefaultRetryPolicy()),
	typesafe.WithCompression(true), // gzip for bodies >= 1 KiB (enabled by default)
	typesafe.WithImages(true),      // default Danger Zone images header
	typesafe.WithLongContext(true), // default Danger Zone long-context header (262k)
	typesafe.WithHeader("X-Environment", "production"),
	typesafe.WithLogger(logger),
)
if err != nil {
	log.Fatal(err)
}
defer client.Close()

Option	Purpose	Environment Fallback	Default
WithAPIKey(string)	Bearer credential sent as Authorization. Required.	TYPESAFE_API_KEY	—
WithBaseURL(string)	API root; trailing slashes are removed.	TYPESAFE_BASE_URL	https://api.typesafe.ai
WithDefaultModel(string)	Model used when a call names none.	TYPESAFE_DEFAULT_MODEL	jev-latest
WithTimeout(time.Duration)	HTTP timeout for one attempt. Must be positive. Adopted from WithHTTPClient if supplied.	—	10s
WithRetryPolicy(*RetryPolicy)	Retry policy for every call.	—	DefaultRetryPolicy()
WithCompression(bool)	Automatically gzip bodies $\ge 1\text{ KiB}$.	—	true
WithImages(bool)	Sends x-typesafe-images: true with every request.	—	false
WithLongContext(bool)	Sends x-typesafe-long-context: true with every request.	—	false
WithHeader(key, value string)	Default header sent with every request.	—	—
WithHeaders(map[string]string)	Merges several default headers.	—	—
WithHTTPClient(*http.Client)	Supplies the client and transport. Mutually exclusive with WithTransport.	—	Default client
WithTransport(RoundTripper)	Supplies transport only. Mutually exclusive with WithHTTPClient.	—	Default pooled transport
WithLogger(*slog.Logger)	Structured logger for requests, responses, and retries.	TYPESAFE_LOG_LEVEL	Discarded

NewClient fails with an *SDKError when:

• no API key is available,
• the timeout is not positive,
• both WithHTTPClient and WithTransport are supplied,
• a retry policy fails validation.

Accessors:

config := client.Config()          // resolved read-only configuration
httpClient := client.HTTPClient()  // underlying *http.Client
err := client.Close()              // release connection pool; idempotent

---

Environment Variables

Variable	Meaning
TYPESAFE_API_KEY	API key. Required unless WithAPIKey supplies one.
TYPESAFE_BASE_URL	API root. Default https://api.typesafe.ai.
TYPESAFE_DEFAULT_MODEL	Default model. Default jev-latest.
TYPESAFE_LOG_LEVEL	debug, info, warn, error, or off. Unset means SDK logs nothing.

Exported as typesafe.APIKeyEnv, typesafe.BaseURLEnv, typesafe.DefaultModelEnv, and typesafe.LogLevelEnv.

---

Per-Call Options

SystemOne and Models.List accept request options that override configuration for a single call:

response, err := client.SystemOne(ctx, state, questions,
	typesafe.WithModel("jev-preview"),
	typesafe.WithCallTimeout(5*time.Second),
	typesafe.WithCallRetry(policy),
	typesafe.WithCallCompression(false), // disable gzip for this call
	typesafe.WithCallImages(true),        // enable images / box questions for this call
	typesafe.WithCallLongContext(true),   // enable 262k context for this call
	typesafe.WithCallHeader("X-Correlation-ID", "1234"),
	typesafe.WithExtraBody(map[string]any{"max_output_tokens": 512}),
)

Option	Effect
WithModel(string)	Overrides the model for this call.
WithCallTimeout(time.Duration)	Overrides the HTTP timeout for one attempt of this call. Must be positive.
WithCallRetry(*RetryPolicy)	Overrides the retry policy for this call.
WithCallCompression(bool)	Overrides request gzip compression for this call.
WithCallImages(bool)	Sets x-typesafe-images: true for this call.
WithCallLongContext(bool)	Sets x-typesafe-long-context: true for this call.
WithAssets(any)	Attaches explicit image assets map (Assets, map[string]Asset, or map[string]any).
WithCallHeader(key, value string)	Sets or overrides one request header.
WithCallHeaders(map[string]string)	Merges several request headers.
WithExtraBody(map[string]any)	Shallow-merges extra top-level body fields. Last write wins.

---

Bring Your Own HTTP Client

client, err := typesafe.NewClient(
	typesafe.WithHTTPClient(&http.Client{
		Transport: myInstrumentedTransport,
		Timeout:   30 * time.Second, // adopted as call timeout
	}),
)

A client or transport you supply is used as-is and closed by Client.Close when it implements io.Closer. See Security for default transport settings.