Configuration

配置选项 (Configuration)

English Version | 简体中文

---

客户端全局配置

在构建 Client 时，显式传入的选项拥有最高优先级，其次是环境变量，最后是 SDK 内置默认值。环境变量若仅包含空白字符，将被视为未设置。

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 压缩（>= 1 KiB 自动压缩，默认开启）
	typesafe.WithImages(true),      // 默认开启图像与 Box 危险区标头
	typesafe.WithLongContext(true), // 开启超长上下文危险区标头 (262k)
	typesafe.WithHeader("X-Environment", "production"),
	typesafe.WithLogger(logger),
)
if err != nil {
	log.Fatal(err)
}
defer client.Close()

全局选项列表

配置选项	说明	环境变量回退	默认值
WithAPIKey(string)	设置 Bearer 认证密钥，通过 Authorization 发送。必填。	TYPESAFE_API_KEY	—
WithBaseURL(string)	API 服务根路径，末尾斜杠会自动剔除。	TYPESAFE_BASE_URL	https://api.typesafe.ai
WithDefaultModel(string)	未显式指定模型时的默认模型标识。	TYPESAFE_DEFAULT_MODEL	jev-latest
WithTimeout(time.Duration)	单次网络尝试的 HTTP 超时时间，必须为正数。若由 WithHTTPClient 提供了客户端且无显式超时，将继承其 Timeout。	—	10s
WithRetryPolicy(*RetryPolicy)	全局网络重试策略。	—	DefaultRetryPolicy()
WithCompression(bool)	是否对 $\ge 1\text{ KiB}$ 的请求体自动启用 Gzip 压缩。	—	true
WithImages(bool)	是否在每个请求中附带 x-typesafe-images: true 危险区标头。	—	false
WithLongContext(bool)	是否在每个请求中附带 x-typesafe-long-context: true 危险区标头。	—	false
WithHeader(k, v string)	设置全局默认请求标头。	—	—
WithHeaders(map[string]string)	批量设置全局默认请求标头。	—	—
WithHTTPClient(*http.Client)	提供自定义 http.Client 及其传输层。与 WithTransport 互斥。	—	内置标准 Client
WithTransport(RoundTripper)	仅提供自定义传输层 Transport。与 WithHTTPClient 互斥。	—	内置连接池 Transport
WithLogger(*slog.Logger)	结构化日志记录器，记录请求、响应与重试信息。	TYPESAFE_LOG_LEVEL	静默丢弃

NewClient 在以下情况将直接返回 *SDKError：

• 未能获取到任何有效的 API Key；
• 设置的超时时间非正数（$\le 0$）；
• 同时提供了 WithHTTPClient 和 WithTransport；
• 重试策略校验未通过（如负的重试次数或退避延迟）。

配置与客户端访问器

config := client.Config()          // 获取解析后的只读配置副本
httpClient := client.HTTPClient()  // 获取底层的 *http.Client
err := client.Close()              // 释放空闲连接池；幂等安全

---

环境变量

环境变量	含义
TYPESAFE_API_KEY	API 密钥。若未通过 WithAPIKey 提供则必填。
TYPESAFE_BASE_URL	API 服务根地址，默认 https://api.typesafe.ai。
TYPESAFE_DEFAULT_MODEL	默认模型，默认 jev-latest。
TYPESAFE_LOG_LEVEL	日志级别：debug、info、warn、error、off。未设置时 SDK 保持完全静默。

上述环境变量名在 SDK 中导出为常量：typesafe.APIKeyEnv、typesafe.BaseURLEnv、typesafe.DefaultModelEnv、typesafe.LogLevelEnv。

---

单次调用局部重载选项 (RequestOption)

SystemOne 和 Models.List 支持局部请求选项，可以在不修改全局 Client 的前提下覆盖单次调用的行为：

response, err := client.SystemOne(ctx, state, questions,
	typesafe.WithModel("jev-preview"),
	typesafe.WithCallTimeout(5*time.Second),
	typesafe.WithCallRetry(customPolicy),
	typesafe.WithCallCompression(false), // 单次调用关闭压缩
	typesafe.WithCallImages(true),        // 单次调用开启图片/Box 标头
	typesafe.WithCallLongContext(true),   // 单次调用开启长上下文标头
	typesafe.WithCallHeader("X-Correlation-ID", "req_998"),
	typesafe.WithExtraBody(map[string]any{"max_output_tokens": 512}),
)

局部选项	效果
WithModel(string)	覆盖本次调用的模型名称。
WithCallTimeout(time.Duration)	覆盖本次调用的单次尝试超时时间。
WithCallRetry(*RetryPolicy)	覆盖本次调用的重试策略。
WithCallCompression(bool)	覆盖本次调用是否启用 Gzip 请求压缩。
WithCallImages(bool)	设置本次调用是否附带 x-typesafe-images: true。
WithCallLongContext(bool)	设置本次调用是否附带 x-typesafe-long-context: true。
WithAssets(any)	显式附加图片资产字典（支持 Assets、map[string]Asset 或 map[string]any）。
WithCallHeader(key, value string)	设置或覆盖单次请求的一个标头。
WithCallHeaders(map[string]string)	批量设置单次请求标头。
WithExtraBody(map[string]any)	向请求体顶层浅合并额外字段。重名词段将覆盖 SDK 字段，对象字段直接替换而不做深层递归合并。

---

自定义 HTTP Client 与 Transport

client, err := typesafe.NewClient(
	typesafe.WithHTTPClient(&http.Client{
		Transport: customInstrumentedTransport,
		Timeout:   30 * time.Second, // 将被 SDK 自动采纳为调用超时
	}),
)

用户传入的 Client 或 Transport 将被原样使用；在调用 client.Close() 时，如果用户传入的 Transport 实现了 io.Closer，SDK 会自动调用其 Close() 方法释放资源。关于 SDK 默认连接池的重定向与 TLS 安全策略，参见 安全机制 (Security)。