Documentation
¶
Overview ¶
Package protocol implements the Google Gen AI wire protocol reused by Gemini and Vertex AI provider endpoints inside the models module.
Constructors:
- NewChat — native genai chat. Full Gemini surface: thinking budget, response modalities, system instructions, safety settings, structured output, tool calling, grounding with Google Search;
- NewEmbeddingModel — gemini-embedding-2 with output_dimensionality truncation;
- NewImageModel — Gemini image generation through Interactions;
- NewStreamingSpeechModel — Gemini 3.1 TTS; Call consumes Stream;
- NewSpeechModel — unary-only Gemini 2.5 TTS via generate_content with audio response modality;
- NewTranscriptionModel — audio-input → text via generate_content (Gemini transcribes any audio attachment).
Token estimation: NewTextCounter wraps CountTokens for model-specific tokenizer-based counts.
The Interactions request carries no Api-Revision header. Google documents that header as a way to pin a dated revision of the surface, and also documents breaking changes to it, so an unpinned caller can be moved by a change to the default revision. Every official example nonetheless sends only x-goog-api-key and Content-Type, which is what this posts: matching the documented access shape is the choice here, because a pinned date is itself a value that goes stale, and Scope cannot pick one on a caller's behalf. A caller who wants the pin supplies an http.Client that adds the header.
Gemini's Context Caching API (cheaper repeated prompts) doesn't fit core/chat's request model and is not exposed.
genai supports two backends: Generative Language (api key) and Vertex AI has its own facade package and construction config.
Index ¶
- Constants
- func ValidateGenerationCompletion(response *genai.GenerateContentResponse) error
- type Chat
- type ChatConfig
- type ClientConfig
- type EmbeddingModel
- type EmbeddingModelConfig
- type GenerationClient
- func (g *GenerationClient) GenerateContent(ctx context.Context, model string, contents []*genai.Content, ...) (*genai.GenerateContentResponse, error)
- func (g *GenerationClient) GenerateContentStream(ctx context.Context, model string, contents []*genai.Content, ...) iter.Seq2[*genai.GenerateContentResponse, error]
- type ImageGenerationOptions
- type ImageGoogleSearchOptions
- type ImageModel
- type ImageModelConfig
- type ImageSafetySetting
- type SpeechModel
- type SpeechModelConfig
- type StreamingSpeechModel
- type TextCounter
- type TextCounterConfig
- type TranscriptionModel
- type TranscriptionModelConfig
Constants ¶
const ( SpeechRequestExtensionKey = "google/speech_request" SpeechResponseExtensionKey = "google/speech_response" TranscriptionRequestExtensionKey = "google/transcription_request" TranscriptionResponseExtensionKey = "google/transcription_response" EmbeddingRequestExtensionKey = "google/embedding_request" EmbeddingResponseExtensionKey = "google/embedding_response" ImageRequestExtensionKey = "google/image_request" ImageResponseExtensionKey = "google/image_response" )
const ( ModelGemini36Flash = "gemini-3.6-flash" ModelGemini35Flash = "gemini-3.5-flash" ModelGemini35FlashLite = "gemini-3.5-flash-lite" ModelGemini31ProPreview = "gemini-3.1-pro-preview" ModelGemini25FlashPreviewTTS = "gemini-2.5-flash-preview-tts" ModelGemini25ProPreviewTTS = "gemini-2.5-pro-preview-tts" ModelGemini31FlashTTSPreview = "gemini-3.1-flash-tts-preview" ModelGemini25FlashImage = "gemini-2.5-flash-image" ModelGemini3ProImage = "gemini-3-pro-image" ModelGemini31FlashImage = "gemini-3.1-flash-image" ModelGemini31FlashLiteImage = "gemini-3.1-flash-lite-image" ModelGeminiEmbedding2 = "gemini-embedding-2" )
const DefaultBaseURL = "https://generativelanguage.googleapis.com"
DefaultBaseURL is the endpoint used when a configuration leaves it empty. It is exported so a deployment can point at a proxy or a regional host by overriding a named value rather than restating the vendor's URL.
const ( // RequestExtensionKey stores provider-specific [genai.GenerateContentConfig] // fields using the SDK's JSON names. Fields owned by Core are rejected. RequestExtensionKey = "google/request" )
const ( // ResponseExtensionKey preserves the complete official GenerateContent // response (or the current official stream chunk). ResponseExtensionKey = "google/response" )
Variables ¶
This section is empty.
Functions ¶
func ValidateGenerationCompletion ¶ added in v0.54.0
func ValidateGenerationCompletion(response *genai.GenerateContentResponse) error
ValidateGenerationCompletion requires native success for every returned candidate. Image generation may produce multiple candidates; unary speech narrows that cardinality separately.
Types ¶
type Chat ¶
type Chat struct {
// contains filtered or unexported fields
}
Chat implements the minimal Core Model and optional Streamer capabilities.
func (*Chat) Stream ¶
func (c *Chat) Stream(ctx context.Context, req *corechat.Request) iter.Seq2[*corechat.ResponseDelta, error]
Stream performs one streaming GenerateContent request. Candidate and logical part offsets are retained only for the lifetime of this stream. A native finish reason ends generation; subsequent content returns corechat.ErrInvalidResponse. Metadata may follow, and completion is published only after the stream ends.
type ChatConfig ¶
type ChatConfig struct {
Provider string
Client ClientConfig
DefaultOptions corechat.Options
}
func (ChatConfig) Validate ¶
func (c ChatConfig) Validate() error
type ClientConfig ¶
type ClientConfig struct {
APIKey string
// Backend selects the genai backend. Zero value falls back to
// [genai.BackendGeminiAPI] — the public Gemini API. Set to
// [genai.BackendVertexAI] for GCP-hosted enterprise deployments;
// Project and Location become required in that mode and APIKey
// is ignored in favor of the supplied [genai.ClientConfig.Credentials]
// (or ADC).
Backend genai.Backend
// Project is the GCP project id, required when Backend ==
// BackendVertexAI. Ignored otherwise.
Project string
// Location is the GCP region (e.g. "us-central1"), required when
// Backend == BackendVertexAI. Ignored otherwise.
Location string
// BaseURL overrides the genai client endpoint. Optional —
// production users should leave it empty (the SDK picks the right
// host per Backend). Useful for mock servers / corporate proxies.
BaseURL string
APIVersion string
// HTTPClient is shared by the official Gen AI SDK and the Interactions
// transport. Optional.
HTTPClient *http.Client
}
func (ClientConfig) Validate ¶
func (c ClientConfig) Validate() error
type EmbeddingModel ¶
type EmbeddingModel struct {
// contains filtered or unexported fields
}
EmbeddingModel wraps Gemini's embed_content endpoint. New integrations use gemini-embedding-2, whose output dimensionality is configurable from 128 to 3072. Core's text-only request intentionally exposes only that model's text input capability; richer multimodal embedding inputs belong in a dedicated protocol rather than being hidden inside text.
func NewEmbeddingModel ¶
func NewEmbeddingModel(ctx context.Context, config EmbeddingModelConfig) (*EmbeddingModel, error)
type EmbeddingModelConfig ¶
type EmbeddingModelConfig struct {
Provider string
Client ClientConfig
DefaultOptions embedding.Options
}
func (EmbeddingModelConfig) Validate ¶
func (e EmbeddingModelConfig) Validate() error
type GenerationClient ¶ added in v0.54.0
type GenerationClient struct {
// contains filtered or unexported fields
}
GenerationClient owns GenerateContent's native request and response boundary. The SDK supplies authentication, DTOs, and generation-config projection; its unchecked response converters are never entered.
func NewGenerationClient ¶ added in v0.54.0
func NewGenerationClient(ctx context.Context, config ClientConfig) (*GenerationClient, error)
func (*GenerationClient) GenerateContent ¶ added in v0.54.0
func (g *GenerationClient) GenerateContent(ctx context.Context, model string, contents []*genai.Content, config *genai.GenerateContentConfig) (*genai.GenerateContentResponse, error)
func (*GenerationClient) GenerateContentStream ¶ added in v0.54.0
func (g *GenerationClient) GenerateContentStream(ctx context.Context, model string, contents []*genai.Content, config *genai.GenerateContentConfig) iter.Seq2[*genai.GenerateContentResponse, error]
type ImageGenerationOptions ¶
type ImageGenerationOptions struct {
AspectRatio string `json:"aspect_ratio,omitempty"`
ImageSize string `json:"image_size,omitempty"`
Delivery string `json:"delivery,omitempty"`
PreviousInteractionID string `json:"previous_interaction_id,omitempty"`
Store *bool `json:"store,omitzero"`
ThinkingLevel string `json:"thinking_level,omitempty"`
ThinkingSummaries string `json:"thinking_summaries,omitempty"`
ServiceTier string `json:"service_tier,omitempty"`
Labels map[string]string `json:"labels,omitempty"`
InputImages []*media.Media `json:"input_images,omitempty"`
GoogleSearch *ImageGoogleSearchOptions `json:"google_search,omitzero"`
SafetySettings []ImageSafetySetting `json:"safety_settings,omitempty"`
}
ImageGenerationOptions carries the current Interactions API controls that do not have provider-neutral equivalents in image.Options. Store it under ImageRequestExtensionKey.
func (*ImageGenerationOptions) UnmarshalJSON ¶ added in v0.58.0
func (i *ImageGenerationOptions) UnmarshalJSON(data []byte) error
type ImageGoogleSearchOptions ¶
type ImageGoogleSearchOptions struct {
SearchTypes []string `json:"search_types,omitempty"`
}
ImageGoogleSearchOptions configures the image-generation guide's google_search tool. SearchTypes accepts "web_search" and "image_search".
type ImageModel ¶
type ImageModel struct {
// contains filtered or unexported fields
}
ImageModel uses the current Gemini Interactions API. Imagen's legacy GenerateImages endpoint is deliberately not exposed: Google deprecated Imagen and scheduled its shutdown for 2026-08-17.
func NewImageModel ¶
func NewImageModel(ctx context.Context, config ImageModelConfig) (*ImageModel, error)
type ImageModelConfig ¶
type ImageModelConfig struct {
Client ClientConfig
DefaultOptions image.Options
}
func (ImageModelConfig) Validate ¶
func (i ImageModelConfig) Validate() error
type ImageSafetySetting ¶
type ImageSafetySetting struct {
Type string `json:"type"`
Threshold string `json:"threshold"`
Method string `json:"method,omitempty"`
}
ImageSafetySetting mirrors the Interactions API safety-setting shape.
type SpeechModel ¶ added in v0.41.0
type SpeechModel struct {
// contains filtered or unexported fields
}
SpeechModel owns Gemini 2.5's unary-only synthesis protocol. Gemini 3.1 uses StreamingSpeechModel for both aggregate and streaming output.
Speed and OutputFormat are not honored: Gemini's TTS has no playback-rate knob. GenerateContent returns 24 kHz signed 16-bit little-endian PCM; callers choose their own container at the application boundary.
func NewSpeechModel ¶ added in v0.41.0
func NewSpeechModel(ctx context.Context, config SpeechModelConfig) (*SpeechModel, error)
type SpeechModelConfig ¶ added in v0.41.0
type SpeechModelConfig struct {
Provider string
Client ClientConfig
DefaultOptions speech.Options
}
func (SpeechModelConfig) Validate ¶ added in v0.41.0
func (s SpeechModelConfig) Validate() error
type StreamingSpeechModel ¶ added in v0.41.0
type StreamingSpeechModel struct {
// contains filtered or unexported fields
}
StreamingSpeechModel exposes the native incremental audio protocol.
func NewStreamingSpeechModel ¶ added in v0.41.0
func NewStreamingSpeechModel(ctx context.Context, config SpeechModelConfig) (*StreamingSpeechModel, error)
type TextCounter ¶ added in v0.21.0
type TextCounter struct {
// contains filtered or unexported fields
}
TextCounter reports input-token counts via Gemini's count_tokens endpoint. Implements tokenizer.TextCounter so it drops into code paths gating on token budgets (RAG chunking, prompt-window checks).
func NewTextCounter ¶ added in v0.21.0
func NewTextCounter(ctx context.Context, config TextCounterConfig) (*TextCounter, error)
type TextCounterConfig ¶ added in v0.21.0
type TextCounterConfig struct {
Client ClientConfig
Model string
}
Token counts vary across model families — supply the same Model name you intend to send chat requests under so the count matches the real billing.
func (TextCounterConfig) Validate ¶ added in v0.21.0
func (t TextCounterConfig) Validate() error
type TranscriptionModel ¶ added in v0.41.0
type TranscriptionModel struct {
// contains filtered or unexported fields
}
TranscriptionModel exposes Gemini's multimodal chat through the transcription interface. Gemini has no /transcribe endpoint — any audio-accepting model returns a transcript when prompted. This adapter uses the stable instruction "Transcribe this audio.".
func NewTranscriptionModel ¶ added in v0.41.0
func NewTranscriptionModel(ctx context.Context, config TranscriptionModelConfig) (*TranscriptionModel, error)
func (*TranscriptionModel) Call ¶ added in v0.41.0
func (t *TranscriptionModel) Call(ctx context.Context, req *transcription.Request) (*transcription.Response, error)
type TranscriptionModelConfig ¶ added in v0.41.0
type TranscriptionModelConfig struct {
Provider string
Client ClientConfig
DefaultOptions transcription.Options
}
func (TranscriptionModelConfig) Validate ¶ added in v0.41.0
func (t TranscriptionModelConfig) Validate() error
Source Files
¶
- api.go
- chat_protocol.go
- chat_protocol_request.go
- chat_protocol_response.go
- constants.go
- dialect.go
- doc.go
- embedding.go
- error.go
- generation_client.go
- generation_completion.go
- generation_options.go
- image.go
- image_api.go
- part_replay_state.go
- response_body.go
- speech.go
- speech_binding.go
- streaming_speech.go
- tokenizer.go
- transcription.go