Panoramica dell'API Gemini

L'API Gemini ti consente di accedere ai più recenti modelli generativi di Google. Dopo aver acquisito familiarità con le funzionalità generali disponibili tramite l'API, prova un tutorial per il linguaggio che preferisci per iniziare a sviluppare.

Modelli

Gemini è una serie di modelli di IA generativa multimodali sviluppati da Google. Gemini possono accettare testo e immagini nei prompt, a seconda della variazione scelta, e restituire risposte di testo.

Per informazioni più dettagliate sui modelli, consulta la pagina Modelli Gemini. Puoi anche utilizzare il metodo list_models per elencare tutti i modelli disponibili, quindi il metodo get_model per ottenere i metadati per un determinato modello.

Dati e progettazione dei prompt

I modelli Gemini specifici accettano sia dati di testo che file multimediali come input. Questa funzionalità crea molte altre possibilità per generare contenuti, analizzare dati e risolvere i problemi. Esistono alcune limitazioni e requisiti da considerare, tra cui il limite generale dei token di input per il modello in uso. Per informazioni sui limiti dei token per modelli specifici, consulta Modelli Gemini.

I prompt che utilizzano l'API Gemini non possono superare i 20 MB. L'API Gemini fornisce un'API File per l'archiviazione temporanea dei file multimediali da utilizzare nei prompt, che consente di fornire dati dei prompt oltre il limite di 20 MB. Per ulteriori informazioni sull'utilizzo dell'API Files e sui formati file supportati per le richieste, consulta Richiesta di file multimediali.

Progettazione dei prompt e input di testo

La creazione di prompt efficaci, o prompt engineering, è una combinazione di arte e scienza. Consulta l'introduzione ai prompt per indicazioni su come approcciare i prompt e la guida Prompt 101 per scoprire i diversi approcci ai prompt.

Generazione di contenuti

L'API Gemini consente di utilizzare dati di testo e immagine per i prompt, a seconda della variante del modello utilizzata. Ad esempio, puoi generare testo da prompt di solo testo o prompt multimodali utilizzando un modello Gemini 1.5. Questa sezione fornisce esempi di codice di base di ognuno. Consulta il riferimento dell'API generateContent per un esempio più dettagliato che copre tutti i parametri.

Input di testo e immagini

Puoi inviare un prompt di testo con un'immagine a un modello Gemini 1.5 per eseguire un'attività legata alla visione. Ad esempio, aggiungere sottotitoli codificati a un'immagine o identificarla.

I seguenti esempi di codice dimostrano un'implementazione di base di un prompt di testo e immagine per ogni lingua supportata:

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)

Consulta il tutorial di Python per vedere lo snippet di codice 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)
}

Per un esempio completo, consulta il tutorial per il passaggio.

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());

Per un esempio completo, consulta il tutorial per Node.js.

Pagine 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());

Per un esempio completo, consulta il tutorial web.

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

Per un esempio completo, consulta il tutorial di Dart (Flutter).

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)

Consulta il tutorial di Swift per un esempio 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)

Per un esempio completo, consulta il tutorial per 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)'"
                  }
                }
              ]
            }
          ]
         }')

Per ulteriori dettagli, consulta il tutorial sull'API REST.

Inserimento solo testo

L'API Gemini può anche gestire l'input di solo testo. Questa funzionalità consente di eseguire attività di elaborazione del linguaggio naturale (NLP), come il completamento e il riassunto del testo.

I seguenti esempi di codice mostrano un'implementazione di base di una richiesta di solo testo per ogni lingua supportata:

Python

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

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

response = model.generate_content(prompt)

Consulta il tutorial di Python per l'esempio 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)
}

Per un esempio completo, consulta il tutorial per il passaggio.

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());

Per un esempio completo, consulta il tutorial per Node.js.

Pagine 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());

Per un esempio completo, consulta il tutorial web.

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

Per un esempio completo, consulta il tutorial di Dart (Flutter).

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)

Consulta il tutorial di Swift per un esempio 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)

Per un esempio completo, consulta il tutorial per 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"}]}
    ]
}'

Per ulteriori dettagli, consulta il tutorial sull'API REST.

Conversazioni a turni multipli (chat)

Puoi utilizzare l'API Gemini per creare esperienze di chat interattive per i tuoi utenti. L'utilizzo della funzionalità di chat dell'API consente di raccogliere più serie di domande e risposte, consentendo agli utenti di passare in modo incrementale verso le risposte o di ricevere assistenza per problemi in più parti. Questa funzionalità è ideale per le applicazioni che richiedono una comunicazione continua, come chatbot, tutor interattivi o assistenti dell'assistenza clienti.

I seguenti esempi di codice mostrano un'implementazione di base dell'interazione via chat per ogni lingua supportata:

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)

Per un esempio completo, guarda la demo sulla chat nel tutorial di Python.

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)
}

Per un esempio completo, guarda la demo sulla chat nel tutorial per Vai.

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());

Per un esempio completo, guarda la demo sulla chat nel tutorial di Node.js.

Pagine 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());

Per un esempio completo, guarda la demo sulla chat nel tutorial web.

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

Per un esempio completo, guarda la demo sulla chat nel tutorial di Dart (Flutter).

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)

Per un esempio completo, guarda la demo della chat nel tutorial di Swift.

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)

Per un esempio completo, consulta il tutorial per 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!"

Per ulteriori dettagli, consulta il tutorial sull'API REST.

Risposte dinamiche

L'API Gemini offre un modo aggiuntivo per ricevere risposte dai modelli di IA generativa: sotto forma di flusso di dati. Una risposta in modalità flusso invia dati incrementali all'applicazione così come vengono generati dal modello. Questa funzionalità ti consente di rispondere rapidamente alla richiesta di un utente per mostrare i progressi e creare un'esperienza più interattiva.

Le risposte dinamiche sono un'opzione per i prompt in formato libero e le chat con i modelli Gemini. I seguenti esempi di codice mostrano come richiedere una risposta riprodotta in streaming per un prompt per ogni lingua supportata:

Python

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

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

Consulta il tutorial di Python per vedere lo snippet di codice 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
}

Per un esempio completo, consulta il tutorial per il passaggio.

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);
}

Per un esempio completo, consulta il tutorial per Node.js.

Pagine 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);
}

Per un esempio completo, consulta il tutorial web.

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);
}

Per un esempio completo, consulta il tutorial di Dart (Flutter).

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")
}

Consulta il tutorial di Swift per un esempio 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
}

Per un esempio completo, consulta il tutorial per 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

Per ulteriori dettagli, consulta il tutorial sull'API REST.

Risposte in formato JSON

A seconda dell'applicazione, potresti volere che la risposta a un prompt venga restituita in un formato di dati strutturati, in particolare se utilizzi le risposte per compilare le interfacce di programmazione. L'API Gemini fornisce un parametro di configurazione per richiedere una risposta in formato JSON.

Puoi avere il JSON di output del modello impostando l'opzione di configurazione response_mime_type su application/json e nel prompt descrivi il formato JSON che vuoi in risposta:

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",
      }
    }'

Mentre i modelli Flash di Gemini 1.5 accettano solo una descrizione testo dello schema JSON che si vuole restituire, i modelli Gemini 1.5 Pro consentono di passare un oggetto di schema (o equivalente di tipo Python) e l'output del modello seguirà rigorosamente questo schema. Questa operazione è nota anche come generazione controllata o decodifica vincolata.

Ad esempio, per ottenere un elenco di oggetti Recipe, passa list[Recipe] al campo response_schema dell'argomento 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"
                }
              }
            }
          }
        }
      }'
  ```

Per saperne di più, consulta la guida rapida alla modalità JSON nel Libro di ricette sull'API Gemini.

Incorporamenti

Il servizio di incorporamento nell'API Gemini genera incorporamenti all'avanguardia per parole, frasi e frasi. Gli incorporamenti risultanti possono essere utilizzati per, tra le altre, attività NLP, come la ricerca semantica, la classificazione del testo e il clustering. Per iniziare, consulta la guida agli incorporamenti e scopri alcuni casi d'uso chiave del servizio di incorporamento.

Passaggi successivi