Cliente Delphi para a API Gemini

14 de abril de 2026 · Componentes

O Google Gemini é uma das famílias de modelos de IA multimodal mais poderosas disponíveis hoje, destacando-se em geração de texto, compreensão de imagens, saídas estruturadas e chamadas de função em uma ampla gama de casos de uso. Para desenvolvedores Delphi que desejam integrar o Gemini em suas aplicações, o sgcWebSockets oferece TsgcHTTP_API_Gemini — um componente nativo e abrangente que encapsula toda a superfície da API Google Gemini.

Seja para criar assistentes conversacionais, gerar dados estruturados, processar imagens, criar embeddings para busca semântica ou orquestrar fluxos de trabalho aumentados por ferramentas, este componente oferece acesso direto a cada recurso do Gemini por meio de código Delphi limpo e tipado. Sem boilerplate REST. Sem manipulação de JSON. Basta soltar o componente, definir sua chave de API e começar a construir.

Cobertura completa da API

Todos os principais recursos da API Google Gemini são suportados de fábrica.

Geração de conteúdo Gere texto a partir de prompts com instruções de sistema opcionais. Ajuste a saída com temperatura, top-p, top-k e sequências de parada.	Streaming em tempo real Transmita respostas token por token usando Server-Sent Events. Construa interfaces responsivas que exibem as respostas conforme são geradas.	Visão Analise imagens enviando dados codificados em base64 com um prompt de texto. O Gemini descreve, interpreta e raciocina sobre conteúdo visual.
Saída JSON estruturada Force o Gemini a retornar JSON válido conforme seu schema. Defina um tipo MIME de resposta e schema para resultados sempre parseáveis.	Chamadas de função Defina funções customizadas com JSON Schema. O Gemini decide quando invocá-las, habilitando fluxos de trabalho agentivos e de múltiplas etapas.	Embeddings Gere embeddings vetoriais para texto. Alimente busca semântica, clustering, classificação e sistemas de recomendação.
Contagem de tokens Conte tokens antes de enviar requisições. Estime custos com precisão e gerencie orçamentos da janela de contexto.	Gerenciamento de modelos Liste todos os modelos Gemini disponíveis ou recupere detalhes de um modelo específico, incluindo limites de tokens de entrada/saída.	Retry e logging integrados Retry automático em falhas transitórias com tentativas e intervalos configuráveis. Log completo de requisições/respostas para depuração.

Primeiros passos

Integre o Google Gemini ao seu projeto Delphi em menos de um minuto. Solte o componente, configure sua chave de API e envie sua primeira mensagem.

// 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;

Dois estilos de API. Cada recurso oferece tanto métodos de conveniência (baseados em strings, código mínimo) quanto classes tipadas de requisição/resposta (controle total, segurança de tipos). Escolha a abordagem que melhor se adapta ao seu caso de uso.

Geração de conteúdo e streaming

A API GenerateContent é a base de toda interação com o Gemini. Envie texto com instruções de sistema opcionais e receba respostas de forma síncrona ou em streaming em tempo real.

Instruções de sistema

Controle o comportamento do Gemini fornecendo uma instrução de sistema que define o contexto, a personalidade ou as restrições da conversa.

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 em tempo real

Para interfaces responsivas, transmita a resposta do Gemini token por token usando Server-Sent Events. Atribua o manipulador de evento OnHTTPAPISSE e chame _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 tipada avançada

Para controle total sobre os parâmetros da requisição — temperatura, top-p, top-k, sequências de parada, máximo de tokens de saída — use as classes tipadas de requisição e resposta.

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;

Visão — Compreensão de imagens

O Gemini é nativamente multimodal. Envie fotografias, capturas de tela, diagramas ou gráficos junto com um prompt de texto e receba descrições detalhadas, extração de dados ou perguntas e respostas visuais.

// 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 de uso. Automatize inspeção de qualidade, gere texto alternativo para acessibilidade, extraia dados de gráficos ou construa recursos de busca visual — tudo a partir de código Delphi nativo.

Saída JSON estruturada

Garanta que o Gemini retorne JSON válido e parseável conforme seu schema exato. Defina um tipo MIME de resposta e schema para eliminar pós-processamento — a resposta está pronta para deserializar diretamente nos seus records 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;

Imposição de schema. Ao definir ResponseMimeType como 'application/json' e fornecer um ResponseSchema, o Gemini garante saída estruturalmente válida sempre.

Chamadas de função

Defina funções customizadas com JSON Schema, e o Gemini decidirá quando e como invocá-las. Esta é a base para construir fluxos de trabalho agentivos e de múltiplas etapas que conectam a IA à sua lógica de negócio.

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

Gere embeddings vetoriais de alta qualidade para texto. Os embeddings alimentam busca semântica, clustering de documentos, motores de recomendação e tarefas de classificação.

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

Para controle total, use a API tipada para acessar o array de valores de embedding brutos.

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;

Contagem de tokens

Estime custos e gerencie orçamentos da janela de contexto com precisão antes de enviar requisições.

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

Gerenciamento de modelos

Consulte os modelos Gemini disponíveis de forma programática. Liste todos os modelos ou recupere detalhes de um ID de modelo específico, incluindo nome de exibição, descrição e limites de tokens.

// 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;

Configuração e opções

Ajuste o comportamento do componente com opções de configuração abrangentes.

Propriedade	Descrição
`GeminiOptions.ApiKey`	Sua chave de API Google Gemini (obrigatória)
`HttpOptions.ReadTimeout`	Timeout de leitura HTTP em milissegundos (padrão: 60000)
`LogOptions.Enabled`	Habilitar log de requisições/respostas
`LogOptions.FileName`	Caminho do arquivo de log para captura de requisições/respostas
`RetryOptions.Enabled`	Retry automático em falhas transitórias (429, 503)
`RetryOptions.Retries`	Número máximo de tentativas de retry (padrão: 3)
`RetryOptions.Wait`	Tempo de espera entre retries em milissegundos (padrão: 3000)

Parâmetros da requisição

Parâmetro	Descrição
`Temperature`	Temperatura de amostragem (0,0–2,0). Valores mais baixos = mais determinístico.
`TopP`	Amostragem nuclear (0,0–1,0). Controla o corte de probabilidade cumulativa.
`TopK`	Amostragem Top-K. Limita a seleção de tokens aos K melhores candidatos.
`MaxOutputTokens`	Número máximo de tokens na resposta (padrão: 4096).
`StopSequences`	Sequências customizadas que interrompem a geração quando encontradas.
`ResponseMimeType`	Formato de saída: 'application/json' para JSON, 'text/plain' para texto.
`ToolChoice`	Controla como o modelo seleciona funções a chamar.