Google GenAI SDK
MarkdownFormato nativo Gemini: Google GenAI SDK para Python e JavaScript e pedidos REST diretos.
Guia completo
Instalação
pip install google-genainpm install @google/genaiLigação
O endereço é https://api.ailoot.ai sem /v1beta: o SDK constrói o caminho /v1beta/models/<modelo>:generateContent automaticamente. Em Python, o endereço é definido através de HttpOptions(base_url=…); em JavaScript, através de httpOptions.baseUrl. O SDK envia a chave no cabeçalho x-goog-api-key.
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"), # sem /v1beta
)
resp = client.models.generate_content(
model="gemini-3.8-flash",
contents="Crie três nomes para um café.",
)
print(resp.text)import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
apiKey: process.env.AILOOT_API_KEY,
httpOptions: { baseUrl: "https://api.ailoot.ai" }, // sem /v1beta
});
const resp = await ai.models.generateContent({
model: "gemini-3.8-flash",
contents: "Crie três nomes para um café.",
});
console.log(resp.text);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": "Crie três nomes para um café."}]}
]
}' O que pode enviar
- Campos de nível superior:
contents,systemInstruction,generationConfig,safetySettings,toolsetoolConfig. generationConfigaceitatemperature,topP,topK,maxOutputTokens,thinkingConfig,responseMimeType(text/plainouapplication/json),responseSchemaouresponseJsonSchema(objeto JSON),stopSequences(array de cadeias de caracteres),candidateCount: 1, um inteiroseed, os valores numéricospresencePenaltyefrequencyPenalty. Os intervalos e as capacidades permitidos dependem do modelo exato; para uma resposta JSON, escolha uma forma de esquema suportada eapplication/json. Nos modelos de texto,responseModalities— apenas["TEXT"].safetySettings— array de objetos comcategory,thresholde o campo opcionalmethod; escolha os valores de acordo com a documentação do modelo exato.- Nos modelos Gemini que suportam o tipo de entrada correspondente,
parts[].inlineDatacontémmimeTypee dados base64 não vazios; o PDF tem de ser um PDF válido.fileDatacontém um endereço públicohttpsno campofileUrie o MIME do tipo de ficheiro. Para YouTube, pode omitir o MIME.http, endereços privados,gs://e objetos Google Files API não são suportados, tal como o carregamento através da Google Files API. Para vídeo, pode acrescentarvideoMetadata:startOffset/endOffsetcomo cadeia de caracteres em segundos (por exemplo,1.5s) efpssuperior a 0 e não superior a 24. O tamanho do corpo, o contexto, a entrada permitida e o limite de resposta são validados de acordo com o modelo e o formato. - As
functionDeclarationsdo cliente são executadas pela sua aplicação. Os modelos de texto também aceitam{"googleSearch": {}}e{"urlContext": {}}: em separado ou em conjunto no arraytools. Nem Google Search nem URL context podem ser combinados comfunctionDeclarationsno mesmo pedido. Para imagens na saída, apenas estão disponíveis funções do cliente. As outras ferramentas incorporadas e a cache explícita não são suportadas. Search/URL context podem exigir uma reserva com base no limite total de entrada; os valores efetivos detoolUsePromptTokenCountsão contabilizados como tokens de entrada. - Se o modelo não suportar um campo, um anexo ou uma combinação de ferramentas, o pedido é rejeitado antes da reserva — não há qualquer débito. Receberá HTTP
400comstatusINVALID_ARGUMENTe a classeinvalid_request(emErrorInfo.reason—INVALID_REQUEST). JSON inválido, erros nos parâmetros do caminho e noutras validações também devolvem400; leia o texto do erro e o Request ID. As capacidades dependem do modelo: consulte os seus formatos e entradas no catálogo.
| Entrada | Tipos MIME suportados |
|---|---|
| Imagens inline | image/png, image/jpeg, image/webp |
| Documentos | 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 |
| Áudio | audio/wav, audio/mp3, audio/mpeg, audio/aiff, audio/aac, audio/ogg, audio/flac |
| Vídeo | video/mp4, video/mpeg, video/mov, video/quicktime, video/avi, video/x-flv, video/mpg, video/webm, video/wmv, video/3gpp |
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"},
)
# Envie uma única vez. Em caso de timeout, consulte o ID do pedido no histórico de utilização antes de tentar novamente.
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
# Indique um ficheiro local real em formato PDF, áudio ou vídeo e o respetivo tipo MIME suportado.
path, mime = pathlib.Path(sys.argv[1]), sys.argv[2]
payload = {"contents": [{"role": "user", "parts": [
{"text": "Descreva brevemente o conteúdo do ficheiro."},
{"inlineData": {"mimeType": mime,
"data": base64.b64encode(path.read_bytes()).decode()}},
]}]}
print(generate("gemini-3.8-flash", payload))
# Anexo alternativo: {"fileData": {"mimeType": mime, "fileUri": public_https_url}}
# Para um URL real do YouTube: {"fileData": {"fileUri": youtube_url}}Ciclo completo de uma função
Envie a declaração, receba functionCall, execute a sua função, devolva functionResponse e peça a resposta seguinte. Preserve todo o content do modelo, incluindo thoughtSignature; não crie a assinatura por sua conta.
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"},
)
# Envie uma única vez. Em caso de timeout, consulte o ID do pedido no histórico de utilização antes de tentar novamente.
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": "Multiplicar dois números",
"parameters": {"type": "object", "properties": {
"a": {"type": "number"}, "b": {"type": "number"}},
"required": ["a", "b"]},
}]}]
contents = [{"role": "user", "parts": [{"text": "Multiplique 7 por 8 com a função"}]}]
for turn in range(4): # Limite o ciclo de ferramentas; não volte a enviar um pedido cujo resultado não esteja claro.
reply = generate("gemini-3.8-flash", {"contents": contents, "tools": tools})
content = reply["candidates"][0]["content"]
contents.append(content) # Mantenha todas (ALL) as partes originais e thoughtSignature sem alterações.
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")Resposta em fluxo
for chunk in client.models.generate_content_stream(
model="gemini-3.8-flash",
contents="Descreva o pôr do sol sobre o mar",
):
print(chunk.text, end="", flush=True)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": "Descreva o pôr do sol sobre o mar"}]}]}' Modelos disponíveis
Existem 27 identificadores disponíveis no formato Gemini: 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.
Os modelos Gemini também estão disponíveis no formato Anthropic Messages — útil para clientes que só suportam esse formato: Anthropic SDK.