Visão geral da API Gemini

A API Gemini oferece acesso aos modelos generativos mais recentes do Google. Depois de se familiarizar com os recursos gerais disponíveis na API, teste o tutorial da sua linguagem preferida para começar a desenvolver.

Modelos

O Gemini é uma série de modelos de IA generativa multimodais desenvolvidos pelo Google. Os modelos do Gemini podem aceitar texto e imagem em comandos, dependendo da variação de modelo escolhida e gerar respostas de texto.

Para informações mais detalhadas sobre modelos, consulte a página Modelos do Gemini. Também é possível usar o método list_models para listar todos os modelos disponíveis e, em seguida, o método get_model para receber os metadados de um modelo específico.

Dados e design dos comandos

Modelos específicos do Gemini aceitam dados de texto e arquivos de mídia como entrada. Esse recurso cria muitas outras possibilidades para gerar conteúdo, analisar dados e resolver problemas. Há algumas limitações e requisitos a serem considerados, incluindo o limite geral de tokens de entrada para o modelo que você está usando. Para informações sobre limites de token para modelos específicos, consulte Modelos do Gemini.

Os comandos que usam a API Gemini não podem ter mais de 20 MB. A API Gemini oferece uma API File para armazenar temporariamente arquivos de mídia para uso em comandos, o que permite fornecer dados de comandos além do limite de 20 MB. Para mais informações sobre como usar a API Files e os formatos de arquivo aceitos para comandos, consulte Como executar comandos com arquivos de mídia.

Design de comandos e entrada de texto

Criar comandos eficazes, ou engenharia de comando, é uma combinação de arte e ciência. Consulte a introdução a comandos (em inglês) para orientações sobre como abordar comandos e o guia de introdução a comandos para saber mais sobre diferentes abordagens.

Geração de conteúdo

A API Gemini permite usar dados de texto e imagem para comandos, dependendo da variação do modelo que você usa. Por exemplo, é possível gerar texto com base em comandos somente de texto ou multimodais usando um modelo do Gemini 1.5. Esta seção fornece exemplos de código básicos de cada um. Consulte a referência da API generateContent para um exemplo mais detalhado que abrange todos os parâmetros.

Entrada de texto e imagem

Você pode enviar um comando de texto com uma imagem para um modelo Gemini 1.5 para realizar uma tarefa relacionada à visão. Por exemplo, legendar uma imagem ou identificar que está em uma imagem.

Os exemplos de código abaixo demonstram uma implementação básica de um comando de texto e imagem para cada linguagem compatível:

Python

model = genai.GenerativeModel('gemini-1.5-flash')

cookie_picture = {
    'mime_type': 'image/png',
    'data': pathlib.Path('cookie.png').read_bytes()
}
prompt = "Do these look store-bought or homemade?"

response = model.generate_content(
    model="gemini-1.5-flash",
    content=[prompt, cookie_picture]
)
print(response.text)

Consulte o tutorial do Python para ver o snippet de código completo.

Go 

vmodel := client.GenerativeModel("gemini-1.5-flash")

data, err := os.ReadFile(filepath.Join("path-to-image", imageFile))
if err != nil {
  log.Fatal(err)
}
resp, err := vmodel.GenerateContent(ctx, genai.Text("Do these look store-bought or homemade?"), genai.ImageData("jpeg", data))
if err != nil {
  log.Fatal(err)
}

Veja o tutorial do Go para um exemplo completo.

Node.js

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

const prompt = "Do these look store-bought or homemade?";
const image = {
  inlineData: {
    data: Buffer.from(fs.readFileSync("cookie.png")).toString("base64"),
    mimeType: "image/png",
  },
};

const result = await model.generateContent([prompt, image]);
console.log(result.response.text());

Consulte o tutorial do Node.js para um exemplo completo.

Web

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

const prompt = "Do these look store-bought or homemade?";
const image = {
  inlineData: {
    data: base64EncodedImage /* see JavaScript quickstart for details */,
    mimeType: "image/png",
  },
};

const result = await model.generateContent([prompt, image]);
console.log(result.response.text());

Veja o tutorial da Web para um exemplo completo.

Dart (Flutter) 

final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
final prompt = 'Do these look store-bought or homemade?';
final imageBytes = await File('cookie.png').readAsBytes();
final content = [
  Content.multi([
    TextPart(prompt),
    DataPart('image/png', imageBytes),
  ])
];

final response = await model.generateContent(content);
print(response.text);

Consulte o tutorial do Dart (Flutter) (link em inglês) para um exemplo completo.

Swift

let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: "API_KEY")
let cookieImage = UIImage(...)
let prompt = "Do these look store-bought or homemade?"

let response = try await model.generateContent(prompt, cookieImage)

Consulte o tutorial do Swift para um exemplo completo.

Android

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",
    apiKey = BuildConfig.apiKey
)

val cookieImage: Bitmap = // ...
val inputContent = content() {
  image(cookieImage)
  text("Do these look store-bought or homemade?")
}

val response = generativeModel.generateContent(inputContent)
print(response.text)

Veja um exemplo completo no tutorial do Android.

cURL

curl https://generativelanguage.googleapis.com/v1/models/gemini-1.5-flash:generateContent?key=${API_KEY} \
    -H 'Content-Type: application/json' \
    -X POST \
    -d @<(echo'{
          "contents":[
            { "parts":[
                {"text": "Do these look store-bought or homemade?"},
                { "inlineData": {
                    "mimeType": "image/png",
                    "data": "'$(base64 -w0 cookie.png)'"
                  }
                }
              ]
            }
          ]
         }')

Consulte o tutorial da API REST para mais detalhes.

Entrada somente de texto

A API Gemini também pode processar apenas entradas de texto. Esse recurso permite executar tarefas de processamento de linguagem natural (PLN), como preenchimento automático e resumo.

Os exemplos de código a seguir demonstram uma implementação básica de um prompt somente de texto para cada linguagem compatível:

Python

model = genai.GenerativeModel('gemini-1.5-flash')

prompt = "Write a story about a magic backpack."

response = model.generate_content(prompt)

Consulte o tutorial do Python para ver o exemplo completo.

Go 

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-1.5-flash")
resp, err := model.GenerateContent(ctx, genai.Text("Write a story about a magic backpack."))
if err != nil {
  log.Fatal(err)
}

Veja o tutorial do Go para um exemplo completo.

Node.js

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const prompt = "Write a story about a magic backpack.";

const result = await model.generateContent(prompt);
console.log(result.response.text());

Consulte o tutorial do Node.js para um exemplo completo.

Web

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const prompt = "Write a story about a magic backpack.";

const result = await model.generateContent(prompt);
console.log(result.response.text());

Veja o tutorial da Web para um exemplo completo.

Dart (Flutter) 

final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
final prompt = 'Write a story about a magic backpack.';
final content = [Content.text(prompt)];
final response = await model.generateContent(content);
print(response.text);

Consulte o tutorial do Dart (Flutter) (link em inglês) para um exemplo completo.

Swift

let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: "API_KEY")
let prompt = "Write a story about a magic backpack."

let response = try await model.generateContent(prompt)

Consulte o tutorial do Swift para um exemplo completo.

Android

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",
    apiKey = BuildConfig.apiKey
)

val prompt = "Write a story about a magic backpack."
val response = generativeModel.generateContent(prompt)
print(response.text)

Veja um exemplo completo no tutorial do Android.

cURL

curl https://generativelanguage.googleapis.com/v1/models/gemini-1.5-flash:generateContent?key=$API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{ "contents":[
      { "parts":[{"text": "Write a story about a magic backpack"}]}
    ]
}'

Consulte o tutorial da API REST para mais detalhes.

Conversas de várias interações (chat)

Você pode usar a API Gemini para criar experiências de chat interativas para seus usuários. O uso do recurso de chat da API permite coletar várias rodadas de perguntas e respostas, permitindo que os usuários avancem em direção às respostas ou recebam ajuda com problemas de várias partes. Esse recurso é ideal para aplicativos que exigem comunicação contínua, como bots de chat, instrutores interativos ou assistentes de suporte ao cliente.

Os exemplos de código abaixo demonstram uma implementação básica da interação por chat para cada linguagem com suporte:

Python

  model = genai.GenerativeModel('gemini-1.5-flash')
  chat = model.start_chat(history=[])

  response = chat.send_message(
      "Pretend you\'re a snowman and stay in character for each response.")
  print(response.text)

  response = chat.send_message(
      "What\'s your favorite season of the year?")
  print(response.text)

Veja a demonstração do chat no tutorial do Python para ver um exemplo completo.

Go 

model := client.GenerativeModel("gemini-1.5-flash")
cs := model.StartChat()
cs.History = []*genai.Content{
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Pretend you're a snowman and stay in character for each response."),
    },
    Role: "user",
  },
  &genai.Content{
    Parts: []genai.Part{
      genai.Text("Hello! It's cold! Isn't that great?"),
    },
    Role: "model",
  },
}

resp, err := cs.SendMessage(ctx, genai.Text("What's your favorite season of the year?"))
if err != nil {
  log.Fatal(err)
}

Veja a demonstração do chat no tutorial do Go para um exemplo completo.

Node.js

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

const chat = model.startChat({
  history: [
    {
      role: "user",
      parts: "Pretend you're a snowman and stay in character for each response.",
    },
    {
      role: "model",
      parts: "Hello! It's cold! Isn't that great?",
    },
  ],
  generationConfig: {
    maxOutputTokens: 100,
  },
});

const msg = "What's your favorite season of the year?";
const result = await chat.sendMessage(msg);
console.log(result.response.text());

Confira a demonstração do chat no tutorial do Node.js para um exemplo completo.

Web

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

const chat = model.startChat({
  history: [
    {
      role: "user",
      parts: "Pretend you're a snowman and stay in character for each response.",
    },
    {
      role: "model",
      parts: "Hello! It's so cold! Isn't that great?",
    },
  ],
  generationConfig: {
    maxOutputTokens: 100,
  },
});

const msg = "What's your favorite season of the year?";
const result = await chat.sendMessage(msg);
console.log(result.response.text());

Confira a demonstração do chat no tutorial da Web para um exemplo completo.

Dart (Flutter) 

final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
final chat = model.startChat(history: [
  Content.text(
      "Pretend you're a snowman and stay in character for each response."),
  Content.model([TextPart("Hello! It's cold! Isn't that great?")]),
]);
final content = Content.text("What's your favorite season of the year?");
final response = await chat.sendMessage(content);
print(response.text);

Confira a demonstração do chat no tutorial do Dart (Flutter) (link em inglês) para um exemplo completo.

Swift

let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: "API_KEY")
let chat = model.startChat()

var message = "Pretend you're a snowman and stay in character for each response."
var response = try await chat.sendMessage(message)

message = "What\'s your favorite season of the year?"
response = try await chat.sendMessage(message)

Veja a demonstração do chat no tutorial do Swift para um exemplo completo.

Android

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",
    apiKey = BuildConfig.apiKey
)

val chat = generativeModel.startChat()
val response = chat.sendMessage("Pretend you're a snowman and stay in
        character for each response.")
print(response.text)

Veja um exemplo completo no tutorial do Android.

cURL

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {"role":"user",
         "parts":[{
           "text": "Pretend you're a snowman and stay in character for each
        {"role": "model",
            response."}]},
         "parts":[{
           "text": "Hello! It's so cold! Isn't that great?"}]},
        {"role": "user",
         "parts":[{
           "text": "What\'s your favorite season of the year?"}]},
       ]
    }' 2> /dev/null | grep "text"
# response example:
"text": "Winter, of course!"

Consulte o tutorial da API REST para mais detalhes.

Respostas transmitidas

A API Gemini oferece outra maneira de receber respostas de modelos de IA generativa: como um fluxo de dados. Uma resposta em streaming envia partes incrementais de dados de volta para o aplicativo conforme eles são gerados pelo modelo. Esse recurso permite responder rapidamente a uma solicitação do usuário para mostrar o progresso e criar uma experiência mais interativa.

As respostas em streaming são uma opção para comandos e conversas em formato livre com os modelos do Gemini. Os exemplos de código a seguir mostram como solicitar uma resposta transmitida para uma solicitação em cada linguagem compatível:

Python

prompt = "Write a story about a magic backpack."

response = genai.stream_generate_content(
    model="models/gemini-1.5-flash",
    prompt=prompt
)

Consulte o tutorial do Python para ver o snippet de código completo.

Go 

ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

model := client.GenerativeModel("gemini-1.5-flash")

iter := model.GenerateContentStream(ctx, genai.Text("Write a story about a magic backpack."))
for {
  resp, err := iter.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }

  // print resp
}

Veja o tutorial do Go para um exemplo completo.

Node.js

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const prompt = "Write a story about a magic backpack.";

const result = await model.generateContentStream([prompt]);
// print text as it comes in
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  console.log(chunkText);
}

Consulte o tutorial do Node.js para um exemplo completo.

Web

const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const prompt = "Write a story about a magic backpack.";

const result = await model.generateContentStream([prompt]);
// print text as it comes in
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  console.log(chunkText);
}

Veja o tutorial da Web para um exemplo completo.

Dart (Flutter) 

final model = GenerativeModel(model: 'gemini-1.5-flash', apiKey: apiKey);
final prompt = 'Write a story about a magic backpack.';
final content = [Content.text(prompt)];
final response = model.generateContentStream(content);
await for (final chunk in response) {
  print(chunk.text);
}

Consulte o tutorial do Dart (Flutter) (link em inglês) para um exemplo completo.

Swift

let model = GenerativeModel(name: "gemini-1.5-flash", apiKey: "API_KEY")
let prompt = "Write a story about a magic backpack."

let stream = model.generateContentStream(prompt)
for try await chunk in stream {
  print(chunk.text ?? "No content")
}

Consulte o tutorial do Swift para um exemplo completo.

Android

val generativeModel = GenerativeModel(
    modelName = "gemini-1.5-flash",
    apiKey = BuildConfig.apiKey
)

val inputContent = content {
  text("Write a story about a magic backpack.")
}

var fullResponse = ""
generativeModel.generateContentStream(inputContent).collect { chunk ->
  print(chunk.text)
  fullResponse += chunk.text
}

Veja um exemplo completo no tutorial do Android.

cURL

curl https://generativelanguage.googleapis.com/v1/models/gemini-1.5-flash:streamGenerateContent?key=${API_KEY} \
    -H 'Content-Type: application/json' \
    --no-buffer \
    -d '{ "contents":[
            {"role": "user",
              "parts":[{"text": "Write a story about a magic backpack."}]
            }
          ]
        }' > response.json

Consulte o tutorial da API REST para mais detalhes.

Respostas no formato JSON

Dependendo do seu aplicativo, talvez você queira que a resposta a uma solicitação seja retornada em um formato de dados estruturados, especialmente se você estiver usando as respostas para preencher interfaces de programação. A API Gemini fornece um parâmetro de configuração para solicitar uma resposta no formato JSON.

É possível fazer com que o modelo gere o JSON. Basta definir a opção de configuração response_mime_type como application/json e, no prompt, descrever o formato de JSON que você quer em resposta:

Python

model = genai.GenerativeModel('gemini-1.5-flash',
                              generation_config={"response_mime_type": "application/json"})

prompt = """
  List 5 popular cookie recipes.

  Using this JSON schema:

    Recipe = {"recipe_name": str}

  Return a `list[Recipe]`
  """

response = model.generate_content(prompt)
print(response.text)

cURL

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$API_KEY \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [
        {
          "parts": [
            {
              "text": "\nList 5 popular cookie recipes.\n\nUsing this JSON schema:\n\n  Recipe = {\"recipe_name\": str}\n\nReturn a `list[Recipe]`\n      "
            }
          ]
        }
      ]
      "generationConfig": {
            "response_mime_type": "application/json",
      }
    }'

Enquanto os modelos de Flash do Gemini 1.5 aceitam apenas uma descrição em texto do esquema JSON que você quer retornar, os modelos Gemini 1.5 Pro permitem que você transmita um objeto de esquema (ou um tipo Python equivalente), e a saída do modelo seguirá estritamente esse esquema. Isso também é conhecido como geração controlada ou decodificação restrita.

Por exemplo, para receber uma lista de objetos Recipe, transmita list[Recipe] para o campo response_schema do argumento generation_config:

Python

import typing_extensions as typing

class Recipe(typing.TypedDict):
  recipe_name: str

model = genai.GenerativeModel(model_name="models/gemini-1.5-pro")

result = model.generate_content(
  "List 5 popular cookie recipes",
  generation_config=genai.GenerationConfig(response_mime_type="application/json",
                                           response_schema = list[Recipe]))

print(result.text)

cURL

  curl https://generativelanguage.googleapis.com/v1beta/models/models/gemini-1.5-pro:generateContent?
      -H 'Content-Type: application/json'
      -X POST \
      -d '{
        "contents": [
          {
            "parts": [
              {
                "text": "List 5 popular cookie recipes"
              }
            ]
          }
        ],
        "generationConfig": {
          "responseMimeType": "application/json",
          "responseSchema": {
            "type": "ARRAY",
            "items": {
              "type": "OBJECT",
              "properties": {
                "recipe_name": {
                  "type": "STRING"
                }
              }
            }
          }
        }
      }'
  ```

Para saber mais, consulte o Guia de início rápido do modo JSON no manual da API Gemini.

Embeddings

O serviço de embedding na API Gemini gera embeddings de última geração para palavras, frases e sentenças. Os embeddings resultantes podem ser usados para tarefas de PLN, como pesquisa semântica, classificação de texto e clustering, entre muitas outras. Consulte o guia de embeddings para saber o que são embeddings e alguns casos de uso principais do serviço para ajudar você a começar.

Próximas etapas