Gemini generateContent

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."}]}
    ]
  }' 

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)

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

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{ "text": "1. «Chicchi e vapore» 2. «La macinatura del mattino» 3. «La caffetteria all’angolo»" }]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  },
  "modelVersion": "gemini-3.8-flash"
}

Autorizzazione

• x-goog-api-keyheaderobbligatorio

  Chiave sk-…. Sono accettati anche Authorization: Bearer oppure x-api-key. Per compatibilità con Google è accettato anche ?key= nell’indirizzo — con la priorità più bassa; ?api_key= viene rifiutato con 400. Consigliamo un header, così la chiave non finisce nei log.

Percorso

• modelstringobbligatorio

  ID di un modello con formato Gemini, ad esempio gemini-3.8-flash oppure gemini-3.1-pro. In totale 27.

Corpo della richiesta

• contentsarrayobbligatorio

  Messaggi con role (user/model) e parts: text, inlineData/fileData, functionCall/functionResponse. Gli allegati devono essere tra quelli accettati in input dal modello.

• systemInstructionobjectfacoltativo

  Istruzione di sistema testuale: {"parts": [{"text": "…"}]}.

• generationConfigobjectfacoltativo

  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"].

• safetySettingsarrayfacoltativo

  Oggetti con i campi obbligatori category e threshold e il campo facoltativo method. I valori devono essere supportati dal modello specifico.

• toolsarrayfacoltativo

  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.

• toolConfigobjectfacoltativo

  functionCallingConfig: mode (AUTO/ANY/NONE/VALIDATED/MODE_UNSPECIFIED), allowedFunctionNames.

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.

PDF, audio, video e link

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.

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

Search e URL context

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.

{"tools": [{"googleSearch": {}}, {"urlContext": {}}]}

Immagini in output

Le immagini nelle risposte in formato Gemini sono supportate solo da gemini-3.1-flash-image. È una capacità distinta rispetto a /v1/images/generations: gli altri modelli di immagini non funzionano qui. Questo modello ha un input fino a 131072 token e una risposta fino a 32768; l’intero costo della risposta più lunga viene riservato in anticipo.

responseModalities — un insieme non vuoto di TEXT/IMAGE senza duplicati. imageConfig.imageSize: 1K/2K/4K; aspectRatio: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, 1:4, 4:1, 1:8, 8:1. L’input di questo modello è testo e PNG/JPEG/WebP inline; PDF/audio/video/fileData e Search/URL context integrati non sono accettati qui. Disponibilità e prezzi per la tua chiave sono nel catalogo e in GET /v1/models.

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

reply = generate("gemini-3.1-flash-image", {
    "contents": [{"role": "user", "parts": [{"text": "Acquerello: un faro all’alba"}]}],
    "generationConfig": {
        "responseModalities": ["TEXT", "IMAGE"],
        "imageConfig": {"aspectRatio": "1:1", "imageSize": "1K"},
    },
})
index = 0
for candidate in reply.get("candidates", []):
    for part in candidate.get("content", {}).get("parts", []):
        if "text" in part:
            print(part["text"])
        blob = part.get("inlineData", {})
        if blob.get("mimeType", "").startswith("image/") and blob.get("data"):
            index += 1
            extension = {"image/png": "png", "image/jpeg": "jpg",
                         "image/webp": "webp"}.get(blob["mimeType"], "bin")
            pathlib.Path(f"gemini-image-v{index}.{extension}").write_bytes(
                base64.b64decode(blob["data"]))
print("All returned images:", index)

Ciclo completo di function calling

Le funzioni sono eseguite dal client. Restituisci tutto il content originale del modello con thoughtSignature senza modifiche, poi functionResponse con gli stessi name e id, se id era presente in functionCall.

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

Risposta

• candidates[].content.partsarray

  Risposta del modello.

• usageMetadataobject

  promptTokenCount, candidatesTokenCount, totalTokenCount.