Source: https://ailoot.ai/docs/it/connect/google-genai/
Canonical: https://ailoot.ai/docs/it/connect/google-genai/
Language: it

[Connessione](https://ailoot.ai/docs/it/) 

# Google GenAI SDK

[Markdown](https://ailoot.ai/docs/it/connect/google-genai/index.md)

Formato nativo Gemini: Google GenAI SDK per Python e JavaScript e richieste REST dirette.

## [](https://ailoot.ai/docs/it/connect/google-genai/#install)Installazione

```bash
pip install google-genai
```

```bash
npm install @google/genai
```

## [](https://ailoot.ai/docs/it/connect/google-genai/#client)Connessione

L’indirizzo è `https://api.ailoot.ai` senza `/v1beta`: l’SDK costruisce il percorso `/v1beta/models/<modello>:generateContent` da solo. In Python l’indirizzo si imposta tramite `HttpOptions(base_url=…)`, in JavaScript tramite `httpOptions.baseUrl`. L’SDK invia la chiave nell’header `x-goog-api-key`.

```python
from google import genai
from google.genai import types
import os

client = genai.Client(
    api_key=os.environ["AILOOT_API_KEY"],
    http_options=types.HttpOptions(base_url="https://api.ailoot.ai"),  # senza /v1beta
)

resp = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Proponi tre nomi per una caffetteria.",
)
print(resp.text)
```

```js
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: process.env.AILOOT_API_KEY,
  httpOptions: { baseUrl: "https://api.ailoot.ai" }, // senza /v1beta
});

const resp = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Proponi tre nomi per una caffetteria.",
});
console.log(resp.text);
```

```bash
curl "https://api.ailoot.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $AILOOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Proponi tre nomi per una caffetteria."}]}
    ]
  }' 
```

## [](https://ailoot.ai/docs/it/connect/google-genai/#body)Cosa puoi trasmettere

- Campi di primo livello: `contents`, `systemInstruction`, `generationConfig`, `safetySettings`, `tools` e `toolConfig`.
- `generationConfig` accetta `temperature`, `topP`, `topK`, `maxOutputTokens`, `thinkingConfig`, `responseMimeType` (`text/plain` oppure `application/json`), `responseSchema` oppure `responseJsonSchema` (oggetto JSON), `stopSequences` (array di stringhe), `candidateCount: 1`, il valore intero `seed`, i valori numerici `presencePenalty` e `frequencyPenalty`. Gli intervalli ammessi e le capacità dipendono dal modello specifico; per una risposta JSON scegli una sola forma di schema supportata e `application/json`. Per i modelli testuali `responseModalities` è solo `["TEXT"]`.
- `safetySettings` — array di oggetti con `category`, `threshold` e il campo facoltativo `method`; scegli i valori in base alla documentazione del modello specifico.
- Per i modelli Gemini che supportano il relativo input, `parts[].inlineData` contiene `mimeType` e dati base64 non vuoti; il PDF deve essere un vero PDF. `fileData` contiene un indirizzo pubblico `https` nel campo `fileUri` e il MIME del tipo di file. Per YouTube il MIME può essere omesso. `http`, gli indirizzi privati, `gs://` e gli oggetti Google Files API non sono supportati, né il caricamento tramite Google Files API. Per i video puoi aggiungere `videoMetadata`: `startOffset`/`endOffset` come stringa in secondi (ad esempio `1.5s`) e `fps` con un valore maggiore di 0 e non superiore a 24. Dimensione del corpo, contesto, input ammessi e limite di risposta sono verificati in base al modello e al formato.
- Le `functionDeclarations` del client sono eseguite dalla tua applicazione. I modelli testuali accettano anche `{"googleSearch": {}}` e `{"urlContext": {}}`: separatamente o insieme nell’array `tools`. Né Google Search né URL context possono essere combinati con `functionDeclarations` nella stessa richiesta. Per l’output di immagini sono disponibili solo le funzioni client. Altri strumenti integrati e cache esplicita non sono supportati. Search/URL context possono richiedere una riserva sull’intero limite di input; il valore effettivo di `toolUsePromptTokenCount` viene conteggiato come token di input.
- Se il modello non supporta un campo, un allegato o una combinazione di strumenti, la richiesta viene rifiutata prima della riserva — non viene addebitato nulla. Riceverai HTTP `400` con `status` `INVALID_ARGUMENT` e classe `invalid_request` (in `ErrorInfo.reason` — `INVALID_REQUEST`). Anche JSON non valido, errori nei parametri del percorso e altre verifiche restituiscono `400`; leggi il testo dell’errore e il Request ID. Le capacità dipendono dal modello: controlla formati e input nel catalogo.

| Input | MIME supportati |
| --- | --- |
| Immagini inline | image/png, image/jpeg, image/webp |
| Documenti | application/pdf; text/plain, text/html, text/css, text/csv, text/xml, text/rtf, text/markdown, text/javascript, application/x-javascript, text/x-python, application/x-python |
| Audio | audio/wav, audio/mp3, audio/mpeg, audio/aiff, audio/aac, audio/ogg, audio/flac |
| Video | video/mp4, video/mpeg, video/mov, video/quicktime, video/avi, video/x-flv, video/mpg, video/webm, video/wmv, video/3gpp |

```python
import json, os, urllib.request

def generate(model, payload):
    req = urllib.request.Request(
        "https://api.ailoot.ai/v1beta/models/" + model + ":generateContent",
        data=json.dumps(payload).encode(),
        headers={"x-goog-api-key": os.environ["AILOOT_API_KEY"],
                 "Content-Type": "application/json"},
    )
    # Un solo invio. Dopo un timeout, verifica il Request ID nella cronologia di utilizzo prima di riprovare.
    with urllib.request.urlopen(req, timeout=300) as response:
        print("Request ID:", response.headers.get("X-Request-ID"))
        return json.load(response)

import base64, pathlib, sys

# Fornisci un file PDF, audio o video locale reale e il relativo tipo MIME supportato.
path, mime = pathlib.Path(sys.argv[1]), sys.argv[2]
payload = {"contents": [{"role": "user", "parts": [
    {"text": "Descrivi brevemente il contenuto del file."},
    {"inlineData": {"mimeType": mime,
                    "data": base64.b64encode(path.read_bytes()).decode()}},
]}]}
print(generate("gemini-3.8-flash", payload))
# Allegato alternativo: {"fileData": {"mimeType": mime, "fileUri": public_https_url}}
# Per un URL YouTube reale: {"fileData": {"fileUri": youtube_url}}
```

## [](https://ailoot.ai/docs/it/connect/google-genai/#function-loop)Ciclo completo di una funzione

Trasmetti la dichiarazione, ricevi functionCall, esegui la tua funzione, restituisci functionResponse e richiedi la risposta successiva. Conserva tutto il content del modello, thoughtSignature incluso; non creare la firma da solo.

```python
import json, os, urllib.request

def generate(model, payload):
    req = urllib.request.Request(
        "https://api.ailoot.ai/v1beta/models/" + model + ":generateContent",
        data=json.dumps(payload).encode(),
        headers={"x-goog-api-key": os.environ["AILOOT_API_KEY"],
                 "Content-Type": "application/json"},
    )
    # Un solo invio. Dopo un timeout, verifica il Request ID nella cronologia di utilizzo prima di riprovare.
    with urllib.request.urlopen(req, timeout=300) as response:
        print("Request ID:", response.headers.get("X-Request-ID"))
        return json.load(response)

tools = [{"functionDeclarations": [{
    "name": "multiply", "description": "Moltiplicare due numeri",
    "parameters": {"type": "object", "properties": {
        "a": {"type": "number"}, "b": {"type": "number"}},
        "required": ["a", "b"]},
}]}]
contents = [{"role": "user", "parts": [{"text": "Moltiplica 7 per 8 usando la funzione"}]}]
for turn in range(4):  # Limita il ciclo di chiamate agli strumenti; non reinviare una richiesta il cui esito è incerto.
    reply = generate("gemini-3.8-flash", {"contents": contents, "tools": tools})
    content = reply["candidates"][0]["content"]
    contents.append(content)  # Mantieni TUTTE le parti originali e thoughtSignature senza modifiche.
    results = []
    for part in content.get("parts", []):
        call = part.get("functionCall")
        if not call:
            continue
        if call["name"] != "multiply":
            raise ValueError("Unexpected function")
        args = call["args"]
        result = {"name": call["name"], "response": {"value": args["a"] * args["b"]}}
        if "id" in call:
            result["id"] = call["id"]
        results.append({"functionResponse": result})
    if not results:
        print(content)
        break
    contents.append({"role": "user", "parts": results})
else:
    raise RuntimeError("Tool loop limit reached")
```

## [](https://ailoot.ai/docs/it/connect/google-genai/#stream)Risposta in streaming

```python
for chunk in client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents="Descrivi un tramonto sul mare",
):
    print(chunk.text, end="", flush=True)
```

```bash
curl -N "https://api.ailoot.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $AILOOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Descrivi un tramonto sul mare"}]}]}' 
```

Ailoot restituisce la risposta Gemini a pagamento dopo il calcolo del costo: il testo del flusso arriva intero quando il modello termina, non parola per parola. Nel flusso Gemini non ci sono righe di servizio, quindi lascia un margine nel timeout del client per risposte lunghe.

## [](https://ailoot.ai/docs/it/connect/google-genai/#models)Modelli disponibili

Nel formato Gemini sono disponibili 27 identificatori: `gemini-3.8-flash`, `gemini-3.1-pro`, `gemini-pro-agent`, `gemini-3.8-flash-tiered`, `gemini-3.8-flash-medium`, `gemini-3.8-flash-low`, `gemini-3.8-flash-high`, `gemini-3.7-flash`, `gemini-3.7-flash-tiered`, `gemini-3.7-flash-medium`, `gemini-3.7-flash-low`, `gemini-3.7-flash-high`, `gemini-3.6-flash`, `gemini-3.6-flash-tiered`, `gemini-3.6-flash-medium`, `gemini-3.6-flash-low`, `gemini-3.6-flash-high`, `gemini-3.5-flash-lite`, `gemini-3.1-pro-preview`, `gemini-3.1-pro-low`, `gemini-3.1-pro-high`, `gemini-3.1-flash-lite`, `gemini-3-flash`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-thinking`, `gemini-2.5-flash-lite`.

I modelli Gemini sono disponibili anche nel formato Anthropic Messages — comodo per i client che supportano solo quello: [Anthropic SDK](https://ailoot.ai/docs/it/connect/anthropic-sdk/).

Hai altre domande? Invia il Request ID e una descrizione — ti aiuteremo a chiarire il problema.[Contatta l’assistenza](mailto:support@ailoot.ai)

## Ailoot · L’azienda e il suo portafoglio di progetti





Ailoot si basa su un’esperienza operativa consolidata, un’ampia base di clienti, un servizio stabile e un controllo costante dei KPI.





L’azienda e il suo portafoglio di progetti: milioni di clienti; vendite nell’ordine dei miliardi ogni mese.





Ailoot mette questa esperienza operativa al servizio dell’accesso API alle funzioni AI nei prodotti dei clienti, negli agenti, nelle applicazioni e nelle automazioni.