Panoramica dell'API Gemini

L'API Gemini ti dà accesso agli ultimi modelli generativi di Google. Dopo aver acquisito familiarità con le funzionalità generali disponibili tramite l'API, prova un tutorial sul linguaggio che preferisci per iniziare a sviluppare.

Modelli

Gemini è una serie di modelli di IA generativa multimodali sviluppati da Google. I modelli Gemini possono accettare testo e immagini nei prompt, a seconda della variante del modello scelta, e restituiscono risposte testuali.

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

Dati e progettazione dei prompt

I modelli Gemini specifici accettano come input sia dati di testo che file multimediali. Questa funzionalità crea molte ulteriori possibilità per la generazione di contenuti, l'analisi dei dati e la risoluzione dei problemi. Esistono alcuni requisiti e limitazioni da considerare, tra cui il limite generale di token di input per il modello in uso. Per informazioni sui limiti di token per modelli specifici, consulta Modelli Gemini.

Le dimensioni dei 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 dei formati file supportati per i prompt, consulta Inviare richieste con file multimediali.

Progettazione dei prompt e input di testo

Creare prompt efficaci, o ingegneria del prompt, è una combinazione di arte e scienza. Consulta l'introduzione ai prompt per indicazioni su come approcciare i prompt e la guida introduttiva ai prompt per scoprire i diversi approcci ai prompt.

Generazione di contenuti

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

Inserimento di testo e immagini

Puoi inviare un prompt di testo con un'immagine a un modello Gemini 1.5 per eseguire un'attività relativa alla visione. Ad esempio, aggiungere didascalie a un'immagine o identificare i contenuti presenti in un'immagine.

I seguenti esempi di codice mostrano un'implementazione di base di un prompt di testo e immagine per ogni linguaggio supportato:

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)

Guarda il tutorial 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 di Go.

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

Consulta il tutorial per Node.js per un esempio completo.

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

Consulta il tutorial web per un esempio completo.

Freccette (flussi) 

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, vedi 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, guarda 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)'"
                  }
                }
              ]
            }
          ]
         }')

Vedi il tutorial sull'API REST per ulteriori dettagli.

Input di 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 un prompt 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 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 di Go.

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

Consulta il tutorial per Node.js per un esempio completo.

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

Consulta il tutorial web per un esempio completo.

Freccette (flussi) 

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

Vedi il tutorial sull'API REST per ulteriori dettagli.

Conversazioni multi-turno (chat)

Puoi utilizzare l'API Gemini per creare esperienze di chat interattive per i tuoi utenti. La funzionalità di chat dell'API consente di raccogliere più serie di domande e risposte, consentendo agli utenti di passare in modo incrementale alle risposte o ricevere assistenza per problemi in più parti. Questa funzionalità è ideale per le applicazioni che richiedono una comunicazione costante, 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)

Guarda la demo della chat nel tutorial Python per un esempio 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)
}

Per un esempio completo, guarda la demo della chat nel tutorial su Go.

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 della chat nel tutorial per 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 in chat nel tutorial web.

Freccette (flussi) 

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 della chat nel tutorial su 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, guarda 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!"

Vedi il tutorial sull'API REST per ulteriori dettagli.

Risposte dinamiche

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

Le risposte trasmesse in streaming 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 in modalità flusso 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
)

Guarda il tutorial 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 di Go.

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

Consulta il tutorial per Node.js per un esempio completo.

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

Consulta il tutorial web per un esempio completo.

Freccette (flussi) 

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, vedi 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, guarda 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

Vedi il tutorial sull'API REST per ulteriori dettagli.

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 completare le interfacce di programmazione. L'API Gemini fornisce un parametro di configurazione per richiedere una risposta in formato JSON.

Puoi fare in modo che il file JSON di output del modello impostando l'opzione di configurazione response_mime_type su application/json e, nel prompt, descrivi il formato di JSON che vuoi nella 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",
      }
    }'

Sebbene i modelli Gemini 1.5 Flash accettino solo una descrizione testo dello schema JSON che vuoi restituire, i modelli Gemini 1.5 Pro ti consentono di passare un oggetto di schema (o un equivalente di tipo Python) e l'output del modello seguirà rigorosamente questo schema. Questa procedura è 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 sulla modalità JSON nel libro di ricette dell'API Gemini.

Incorporamenti

Il servizio di incorporamento nell'API Gemini genera incorporamenti all'avanguardia per parole, frasi e frasi. Gli incorporamenti risultanti possono quindi essere utilizzati per attività NLP come la ricerca semantica, la classificazione del testo e il clustering, tra molte altre. Consulta la guida agli incorporamenti per scoprire cosa sono gli incorporamenti e alcuni casi d'uso chiave del servizio di incorporamento per aiutarti a iniziare.

Passaggi successivi