Client API Gemini per Delphi

14 aprile 2026 · Componenti

Google Gemini è una delle famiglie di modelli IA multimodali più potenti oggi disponibili: eccelle nella generazione di testo, comprensione di immagini, output strutturati e function calling in un'ampia gamma di casi d'uso. Per gli sviluppatori Delphi che vogliono integrare Gemini nelle loro applicazioni, sgcWebSockets fornisce TsgcHTTP_API_Gemini — un componente nativo e completo che incapsula l'intera superficie dell'API Google Gemini.

Che tu stia costruendo assistenti conversazionali, generando dati strutturati, elaborando immagini, creando embeddings per la ricerca semantica o orchestrando workflow con tool, questo componente ti dà accesso diretto a ogni funzionalità di Gemini tramite codice Delphi pulito e type-safe. Nessun boilerplate REST. Nessuna gestione manuale di JSON. Trascina il componente, imposta la tua API key e inizia a costruire.

Copertura API completa

Ogni funzionalità principale dell'API Google Gemini è supportata out of the box.

Generazione di contenuti Genera testo da prompt con istruzioni di sistema opzionali. Affina l'output con temperature, top-p, top-k e stop sequence.	Streaming in tempo reale Riceve le risposte token per token tramite Server-Sent Events. Costruisci UI reattive che mostrano le risposte mentre vengono generate.	Vision Analizza immagini inviando dati codificati in base64 insieme a un prompt testuale. Gemini descrive, interpreta e ragiona sui contenuti visivi.
Output JSON strutturato Costringe Gemini a restituire JSON valido conforme al tuo schema. Imposta un MIME type di risposta e uno schema per ottenere risultati garantiti e parsabili.	Function calling Definisci funzioni personalizzate con JSON Schema. Gemini decide quando richiamarle, abilitando workflow agentici multi-step.	Embeddings Genera embeddings vettoriali per il testo. Alimenta ricerca semantica, clustering, classificazione e sistemi di raccomandazione.
Conteggio dei token Conta i token prima di inviare le richieste. Stima accuratamente i costi e gestisci i budget della context window.	Gestione dei modelli Elenca tutti i modelli Gemini disponibili o recupera i dettagli di un modello specifico, inclusi i limiti di token in input/output.	Retry e logging integrati Retry automatico in caso di guasti transitori con tentativi e intervalli di attesa configurabili. Logging completo di richieste e risposte per il debug.

Per iniziare

Integra Google Gemini nel tuo progetto Delphi in meno di un minuto. Trascina il componente, configura la tua API key e invia il tuo primo messaggio.

// Create the component and configure the API key
var
  Gemini: TsgcHTTP_API_Gemini;
  vResponse: string;
begin
  Gemini := TsgcHTTP_API_Gemini.Create(nil);
  Try
    Gemini.GeminiOptions.ApiKey := 'YOUR_API_KEY';
    // Send a simple message to Gemini
    vResponse := Gemini._CreateContent(
      'gemini-2.5-flash', 'Hello, Gemini!');
    ShowMessage(vResponse);
  Finally
    Gemini.Free;
  End;
end;

Due stili di API. Ogni funzionalità offre sia metodi di convenienza (string-based, minimo codice) sia classi tipizzate di request/response (controllo completo, type safety). Scegli l'approccio più adatto al tuo caso d'uso.

Generazione di contenuti e streaming

L'API GenerateContent è il fondamento di ogni interazione con Gemini. Invia testo con istruzioni di sistema opzionali e ricevi risposte in modo sincrono o in streaming in tempo reale.

Istruzioni di sistema

Controlla il comportamento di Gemini fornendo un'istruzione di sistema che imposti contesto, personalità o vincoli per la conversazione.

vResponse := Gemini._CreateContentWithSystem(
  'gemini-2.5-flash',
  'You are a helpful assistant that responds in Spanish.',
  'What is the capital of France?');
// Returns: "La capital de Francia es París."

Streaming in tempo reale

Per interfacce utente reattive, ricevi la risposta di Gemini token per token tramite Server-Sent Events. Assegna l'handler dell'evento OnHTTPAPISSE e richiama _CreateContentStream.

// Enable streaming via SSE
Gemini.OnHTTPAPISSE := OnSSEEvent;
Gemini._CreateContentStream('gemini-2.5-flash',
  'Tell me a story about a brave explorer.');
procedure TForm1.OnSSEEvent(Sender: TObject;
  const aEvent, aData: string; var Cancel: Boolean);
begin
  // aData: JSON payload with generated content
  Memo1.Lines.Add(aData);
end;

API tipizzata avanzata

Per il pieno controllo sui parametri della richiesta — temperature, top-p, top-k, stop sequence, max output token — usa le classi tipizzate di request e response.

var
  oRequest: TsgcGeminiClass_Request_GenerateContent;
  oResponse: TsgcGeminiClass_Response_GenerateContent;
begin
  oRequest := TsgcGeminiClass_Request_GenerateContent.Create;
  Try
    oRequest.Model := 'gemini-2.5-flash';
    oRequest.SystemInstruction := 'You are a helpful assistant.';
    oRequest.MaxOutputTokens := 2048;
    oRequest.Temperature := 0.7;
    oRequest.TopP := 0.9;
    oRequest.TopK := 40;
    oRequest.Contents.Add('user', 'Explain quantum computing in simple terms.');
    oResponse := Gemini.CreateContent(oRequest);
    Try
      if Length(oResponse.Candidates) > 0 then
        ShowMessage(oResponse.Candidates[0].Parts[0].Text);
    Finally
      oResponse.Free;
    End;
  Finally
    oRequest.Free;
  End;
end;

Vision — comprensione delle immagini

Gemini è multimodale in modo nativo. Invia fotografie, screenshot, diagrammi o grafici insieme a un prompt testuale e ricevi descrizioni dettagliate, estrazione dati o domande/risposte visive.

// Load an image and ask Gemini to describe it
var
  vBase64: string;
begin
  vBase64 := sgcBase64Encode(LoadFileToBytes('product-photo.png'));
  ShowMessage(Gemini._CreateVisionContent(
    'gemini-2.5-flash',
    'Describe this product image for an e-commerce listing.',
    vBase64, 'image/png'));
end;

Caso d'uso. Automatizza ispezioni di qualità, genera alt-text per l'accessibilità, estrai dati dai grafici o crea funzionalità di ricerca visiva — tutto da codice Delphi nativo.

Output JSON strutturato

Garantisci che Gemini restituisca JSON valido e parsabile conforme al tuo schema esatto. Imposta un MIME type di risposta e uno schema per eliminare il post-processing — la risposta è pronta per essere deserializzata direttamente nei tuoi record Delphi.

var
  vSchema, vResponse: string;
begin
  vSchema :=
    '{"type":"object","properties":{"name":{"type":"string"},' +
    '"age":{"type":"integer"}},"required":["name","age"]}';
  vResponse := Gemini._CreateContentJSON(
    'gemini-2.5-flash',
    'Extract the name and age: John is 30 years old.',
    vSchema);
  // Returns: {"name": "John", "age": 30}
end;

Conformità allo schema. Impostando ResponseMimeType a 'application/json' e fornendo uno ResponseSchema, Gemini garantisce ogni volta un output strutturalmente valido.

Function calling

Definisci funzioni personalizzate con JSON Schema e Gemini deciderà quando e come richiamarle. È la base per costruire workflow agentici multi-step che collegano l'IA alla tua logica di business.

var
  oRequest: TsgcGeminiClass_Request_GenerateContent;
  oFunc: TsgcGeminiClass_Request_FunctionDeclaration;
  oResponse: TsgcGeminiClass_Response_GenerateContent;
begin
  oRequest := TsgcGeminiClass_Request_GenerateContent.Create;
  Try
    oRequest.Model := 'gemini-2.5-flash';
    // Define a function
    oFunc := TsgcGeminiClass_Request_FunctionDeclaration.Create;
    oFunc.Name := 'get_weather';
    oFunc.Description := 'Get the current weather in a location';
    oFunc.Parameters :=
      '{"type":"object","properties":{"location":{"type":"string"}}}';
    oRequest.FunctionDeclarations.Add(oFunc);
    oRequest.Contents.Add('user',
      'What is the weather in Madrid?');
    oResponse := Gemini.CreateContent(oRequest);
    Try
      // Check if Gemini wants to call a function
      if oResponse.Candidates[0].Parts[0].FunctionCallName  '' then
      begin
        ShowMessage('Function: ' + oResponse.Candidates[0].Parts[0].FunctionCallName);
        ShowMessage('Args: ' + oResponse.Candidates[0].Parts[0].FunctionCallArgs);
      end;
    Finally
      oResponse.Free;
    End;
  Finally
    oRequest.Free;
  End;
end;

Embeddings

Genera embeddings vettoriali di alta qualità per il testo. Gli embeddings alimentano ricerca semantica, clustering di documenti, motori di raccomandazione e attività di classificazione.

// Generate embeddings for a text
var
  vEmbedding: string;
begin
  vEmbedding := Gemini._EmbedContent(
    'text-embedding-004',
    'Delphi is a powerful programming language.');
  ShowMessage(vEmbedding);
end;

Per il pieno controllo, usa l'API tipizzata per accedere all'array grezzo dei valori dell'embedding.

var
  oResponse: TsgcGeminiClass_Response_Embedding;
  i: Integer;
begin
  oResponse := Gemini.EmbedContent(
    'text-embedding-004',
    'Delphi is a powerful programming language.');
  Try
    for i := 0 to Length(oResponse.Values) - 1 do
      Memo1.Lines.Add(FloatToStr(oResponse.Values[i]));
  Finally
    oResponse.Free;
  End;
end;

Conteggio dei token

Stima i costi e gestisci accuratamente i budget della context window prima di inviare le richieste.

var
  vTokens: string;
begin
  vTokens := Gemini._CountTokens(
    'gemini-2.5-flash',
    'How many tokens does this message consume?');
  ShowMessage(vTokens);
end;

Gestione dei modelli

Interroga a livello programmatico i modelli Gemini disponibili. Elenca tutti i modelli o recupera i dettagli per un ID modello specifico, incluso il nome visualizzato, la descrizione e i limiti di token.

// List all available Gemini models
vModels := Gemini._GetModels;
// Get details for a specific model
vModel := Gemini._GetModel('gemini-2.5-flash');
// Typed API: access model properties directly
var
  oModel: TsgcGeminiClass_Response_Model;
begin
  oModel := Gemini.GetModel('gemini-2.5-flash');
  Try
    ShowMessage('Name: ' + oModel.DisplayName);
    ShowMessage('Input limit: ' + IntToStr(oModel.InputTokenLimit));
    ShowMessage('Output limit: ' + IntToStr(oModel.OutputTokenLimit));
  Finally
    oModel.Free;
  End;
end;

Configurazione e opzioni

Affina il comportamento del componente con un set completo di opzioni di configurazione.

Proprietà	Descrizione
`GeminiOptions.ApiKey`	La tua chiave API Google Gemini (obbligatoria)
`HttpOptions.ReadTimeout`	Timeout di lettura HTTP in millisecondi (default: 60000)
`LogOptions.Enabled`	Abilita il logging di richieste e risposte
`LogOptions.FileName`	Percorso del file di log per acquisire richieste e risposte
`RetryOptions.Enabled`	Retry automatico in caso di guasti transitori (429, 503)
`RetryOptions.Retries`	Numero massimo di tentativi di retry (default: 3)
`RetryOptions.Wait`	Tempo di attesa tra i retry in millisecondi (default: 3000)

Parametri della richiesta

Parametro	Descrizione
`Temperature`	Temperatura di campionamento (0.0–2.0). Valori più bassi = più deterministico.
`TopP`	Nucleus sampling (0.0–1.0). Controlla la soglia di probabilità cumulativa.
`TopK`	Top-K sampling. Limita la selezione dei token ai primi K candidati.
`MaxOutputTokens`	Numero massimo di token nella risposta (default: 4096).
`StopSequences`	Sequenze personalizzate che fermano la generazione quando vengono incontrate.
`ResponseMimeType`	Formato di output: 'application/json' per JSON, 'text/plain' per testo.
`ToolChoice`	Controlla come il modello seleziona le funzioni da richiamare.