feat(api): Realtime API token_limits, Hybrid searching ranking options

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 123
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-f68f718cd45ac3f9336603601bccc38a718af44d0b26601031de3d0a71b7ce2f.yml
-openapi_spec_hash: 1560717860bba4105936647dde8f618d
-config_hash: 50ee3382a63c021a9f821a935950e926
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-3c5d1593d7c6f2b38a7d78d7906041465ee9d6e9022f0651e1da194654488108.yml
+openapi_spec_hash: 0a4d8ad2469823ce24a3fd94f23f1c2b
+config_hash: 032995825500a503a76da119f5354905

aliases.go

@@ -294,9 +294,13 @@ type CompoundFilterParam = shared.CompoundFilterParam
 // This is an alias to an internal type.
 type CustomToolInputFormatUnion = shared.CustomToolInputFormatUnion
 
+// Unconstrained free-form text.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatText = shared.CustomToolInputFormatText
 
+// A grammar defined by the user.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatGrammar = shared.CustomToolInputFormatGrammar
 
@@ -305,9 +309,13 @@ type CustomToolInputFormatGrammar = shared.CustomToolInputFormatGrammar
 // This is an alias to an internal type.
 type CustomToolInputFormatUnionParam = shared.CustomToolInputFormatUnionParam
 
+// Unconstrained free-form text.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatTextParam = shared.CustomToolInputFormatTextParam
 
+// A grammar defined by the user.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatGrammarParam = shared.CustomToolInputFormatGrammarParam
 

conversations/aliases.go

@@ -294,9 +294,13 @@ type CompoundFilterParam = shared.CompoundFilterParam
 // This is an alias to an internal type.
 type CustomToolInputFormatUnion = shared.CustomToolInputFormatUnion
 
+// Unconstrained free-form text.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatText = shared.CustomToolInputFormatText
 
+// A grammar defined by the user.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatGrammar = shared.CustomToolInputFormatGrammar
 
@@ -305,9 +309,13 @@ type CustomToolInputFormatGrammar = shared.CustomToolInputFormatGrammar
 // This is an alias to an internal type.
 type CustomToolInputFormatUnionParam = shared.CustomToolInputFormatUnionParam
 
+// Unconstrained free-form text.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatTextParam = shared.CustomToolInputFormatTextParam
 
+// A grammar defined by the user.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatGrammarParam = shared.CustomToolInputFormatGrammarParam
 

image.go

@@ -960,7 +960,10 @@ type ImageEditParams struct {
 	//
 	// Any of "transparent", "opaque", "auto".
 	Background ImageEditParamsBackground `json:"background,omitzero"`
-	// Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
+	// Control how much effort the model will exert to match the style and features,
+	// especially facial features, of input images. This parameter is only supported
+	// for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and
+	// `low`. Defaults to `low`.
 	//
 	// Any of "high", "low".
 	InputFidelity ImageEditParamsInputFidelity `json:"input_fidelity,omitzero"`
@@ -1059,7 +1062,10 @@ const (
 	ImageEditParamsBackgroundAuto        ImageEditParamsBackground = "auto"
 )
 
-// Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
+// Control how much effort the model will exert to match the style and features,
+// especially facial features, of input images. This parameter is only supported
+// for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and
+// `low`. Defaults to `low`.
 type ImageEditParamsInputFidelity string
 
 const (

realtime/aliases.go

@@ -294,9 +294,13 @@ type CompoundFilterParam = shared.CompoundFilterParam
 // This is an alias to an internal type.
 type CustomToolInputFormatUnion = shared.CustomToolInputFormatUnion
 
+// Unconstrained free-form text.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatText = shared.CustomToolInputFormatText
 
+// A grammar defined by the user.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatGrammar = shared.CustomToolInputFormatGrammar
 
@@ -305,9 +309,13 @@ type CustomToolInputFormatGrammar = shared.CustomToolInputFormatGrammar
 // This is an alias to an internal type.
 type CustomToolInputFormatUnionParam = shared.CustomToolInputFormatUnionParam
 
+// Unconstrained free-form text.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatTextParam = shared.CustomToolInputFormatTextParam
 
+// A grammar defined by the user.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatGrammarParam = shared.CustomToolInputFormatGrammarParam
 

realtime/clientsecret.go

@@ -124,8 +124,19 @@ type RealtimeSessionCreateResponse struct {
 	// `auto` will create a trace for the session with default values for the workflow
 	// name, group id, and metadata.
 	Tracing RealtimeSessionCreateResponseTracingUnion `json:"tracing,nullable"`
-	// Controls how the realtime conversation is truncated prior to model inference.
-	// The default is `auto`.
+	// When the number of tokens in a conversation exceeds the model's input token
+	// limit, the conversation be truncated, meaning messages (starting from the
+	// oldest) will not be included in the model's context. A 32k context model with
+	// 4,096 max output tokens can only include 28,224 tokens in the context before
+	// truncation occurs. Clients can configure truncation behavior to truncate with a
+	// lower max token limit, which is an effective way to control token usage and
+	// cost. Truncation will reduce the number of cached tokens on the next turn
+	// (busting the cache), since messages are dropped from the beginning of the
+	// context. However, clients can also configure truncation to retain messages up to
+	// a fraction of the maximum context size, which will reduce the need for future
+	// truncations and thus improve the cache rate. Truncation can be disabled
+	// entirely, which means the server will never truncate but would instead return an
+	// error if the conversation exceeds the model's input token limit.
 	Truncation RealtimeTruncationUnion `json:"truncation"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
 	JSON struct {

realtime/realtime.go

@@ -853,8 +853,19 @@ type RealtimeSessionCreateRequestParam struct {
 	ToolChoice RealtimeToolChoiceConfigUnionParam `json:"tool_choice,omitzero"`
 	// Tools available to the model.
 	Tools RealtimeToolsConfigParam `json:"tools,omitzero"`
-	// Controls how the realtime conversation is truncated prior to model inference.
-	// The default is `auto`.
+	// When the number of tokens in a conversation exceeds the model's input token
+	// limit, the conversation be truncated, meaning messages (starting from the
+	// oldest) will not be included in the model's context. A 32k context model with
+	// 4,096 max output tokens can only include 28,224 tokens in the context before
+	// truncation occurs. Clients can configure truncation behavior to truncate with a
+	// lower max token limit, which is an effective way to control token usage and
+	// cost. Truncation will reduce the number of cached tokens on the next turn
+	// (busting the cache), since messages are dropped from the beginning of the
+	// context. However, clients can also configure truncation to retain messages up to
+	// a fraction of the maximum context size, which will reduce the need for future
+	// truncations and thus improve the cache rate. Truncation can be disabled
+	// entirely, which means the server will never truncate but would instead return an
+	// error if the conversation exceeds the model's input token limit.
 	Truncation RealtimeTruncationUnionParam `json:"truncation,omitzero"`
 	// The type of session to create. Always `realtime` for the Realtime API.
 	//
@@ -1697,10 +1708,13 @@ type RealtimeTruncationUnion struct {
 	RetentionRatio float64 `json:"retention_ratio"`
 	// This field is from variant [RealtimeTruncationRetentionRatio].
 	Type constant.RetentionRatio `json:"type"`
-	JSON struct {
+	// This field is from variant [RealtimeTruncationRetentionRatio].
+	TokenLimits RealtimeTruncationRetentionRatioTokenLimits `json:"token_limits"`
+	JSON        struct {
 		OfRealtimeTruncationStrategy respjson.Field
 		RetentionRatio               respjson.Field
 		Type                         respjson.Field
+		TokenLimits                  respjson.Field
 		raw                          string
 	} `json:"-"`
 }
@@ -1778,15 +1792,21 @@ func (u *RealtimeTruncationUnionParam) asAny() any {
 // input token limit. This allows you to amortize truncations across multiple
 // turns, which can help improve cached token usage.
 type RealtimeTruncationRetentionRatio struct {
-	// Fraction of post-instruction conversation tokens to retain (0.0 - 1.0) when the
-	// conversation exceeds the input token limit.
+	// Fraction of post-instruction conversation tokens to retain (`0.0` - `1.0`) when
+	// the conversation exceeds the input token limit. Setting this to `0.8` means that
+	// messages will be dropped until 80% of the maximum allowed tokens are used. This
+	// helps reduce the frequency of truncations and improve cache rates.
 	RetentionRatio float64 `json:"retention_ratio,required"`
 	// Use retention ratio truncation.
 	Type constant.RetentionRatio `json:"type,required"`
+	// Optional custom token limits for this truncation strategy. If not provided, the
+	// model's default token limits will be used.
+	TokenLimits RealtimeTruncationRetentionRatioTokenLimits `json:"token_limits"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
 	JSON struct {
 		RetentionRatio respjson.Field
 		Type           respjson.Field
+		TokenLimits    respjson.Field
 		ExtraFields    map[string]respjson.Field
 		raw            string
 	} `json:"-"`
@@ -1808,15 +1828,43 @@ func (r RealtimeTruncationRetentionRatio) ToParam() RealtimeTruncationRetentionR
 	return param.Override[RealtimeTruncationRetentionRatioParam](json.RawMessage(r.RawJSON()))
 }
 
+// Optional custom token limits for this truncation strategy. If not provided, the
+// model's default token limits will be used.
+type RealtimeTruncationRetentionRatioTokenLimits struct {
+	// Maximum tokens allowed in the conversation after instructions (which including
+	// tool definitions). For example, setting this to 5,000 would mean that truncation
+	// would occur when the conversation exceeds 5,000 tokens after instructions. This
+	// cannot be higher than the model's context window size minus the maximum output
+	// tokens.
+	PostInstructions int64 `json:"post_instructions"`
+	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
+	JSON struct {
+		PostInstructions respjson.Field
+		ExtraFields      map[string]respjson.Field
+		raw              string
+	} `json:"-"`
+}
+
+// Returns the unmodified JSON received from the API
+func (r RealtimeTruncationRetentionRatioTokenLimits) RawJSON() string { return r.JSON.raw }
+func (r *RealtimeTruncationRetentionRatioTokenLimits) UnmarshalJSON(data []byte) error {
+	return apijson.UnmarshalRoot(data, r)
+}
+
 // Retain a fraction of the conversation tokens when the conversation exceeds the
 // input token limit. This allows you to amortize truncations across multiple
 // turns, which can help improve cached token usage.
 //
 // The properties RetentionRatio, Type are required.
 type RealtimeTruncationRetentionRatioParam struct {
-	// Fraction of post-instruction conversation tokens to retain (0.0 - 1.0) when the
-	// conversation exceeds the input token limit.
+	// Fraction of post-instruction conversation tokens to retain (`0.0` - `1.0`) when
+	// the conversation exceeds the input token limit. Setting this to `0.8` means that
+	// messages will be dropped until 80% of the maximum allowed tokens are used. This
+	// helps reduce the frequency of truncations and improve cache rates.
 	RetentionRatio float64 `json:"retention_ratio,required"`
+	// Optional custom token limits for this truncation strategy. If not provided, the
+	// model's default token limits will be used.
+	TokenLimits RealtimeTruncationRetentionRatioTokenLimitsParam `json:"token_limits,omitzero"`
 	// Use retention ratio truncation.
 	//
 	// This field can be elided, and will marshal its zero value as "retention_ratio".
@@ -1831,3 +1879,23 @@ func (r RealtimeTruncationRetentionRatioParam) MarshalJSON() (data []byte, err e
 func (r *RealtimeTruncationRetentionRatioParam) UnmarshalJSON(data []byte) error {
 	return apijson.UnmarshalRoot(data, r)
 }
+
+// Optional custom token limits for this truncation strategy. If not provided, the
+// model's default token limits will be used.
+type RealtimeTruncationRetentionRatioTokenLimitsParam struct {
+	// Maximum tokens allowed in the conversation after instructions (which including
+	// tool definitions). For example, setting this to 5,000 would mean that truncation
+	// would occur when the conversation exceeds 5,000 tokens after instructions. This
+	// cannot be higher than the model's context window size minus the maximum output
+	// tokens.
+	PostInstructions param.Opt[int64] `json:"post_instructions,omitzero"`
+	paramObj
+}
+
+func (r RealtimeTruncationRetentionRatioTokenLimitsParam) MarshalJSON() (data []byte, err error) {
+	type shadow RealtimeTruncationRetentionRatioTokenLimitsParam
+	return param.MarshalObject(r, (*shadow)(&r))
+}
+func (r *RealtimeTruncationRetentionRatioTokenLimitsParam) UnmarshalJSON(data []byte) error {
+	return apijson.UnmarshalRoot(data, r)
+}

responses/aliases.go

@@ -294,9 +294,13 @@ type CompoundFilterParam = shared.CompoundFilterParam
 // This is an alias to an internal type.
 type CustomToolInputFormatUnion = shared.CustomToolInputFormatUnion
 
+// Unconstrained free-form text.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatText = shared.CustomToolInputFormatText
 
+// A grammar defined by the user.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatGrammar = shared.CustomToolInputFormatGrammar
 
@@ -305,9 +309,13 @@ type CustomToolInputFormatGrammar = shared.CustomToolInputFormatGrammar
 // This is an alias to an internal type.
 type CustomToolInputFormatUnionParam = shared.CustomToolInputFormatUnionParam
 
+// Unconstrained free-form text.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatTextParam = shared.CustomToolInputFormatTextParam
 
+// A grammar defined by the user.
+//
 // This is an alias to an internal type.
 type CustomToolInputFormatGrammarParam = shared.CustomToolInputFormatGrammarParam