docs
Ligação

Google GenAI SDK

Markdown

Formato nativo Gemini: Google GenAI SDK para Python e JavaScript e pedidos REST diretos.

Guia completo

Instalação

pip install google-genai

Ligaçã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)

O que pode enviar

  • Campos de nível superior: contents, systemInstruction, generationConfig, safetySettings, tools e toolConfig.
  • generationConfig aceita temperature, topP, topK, maxOutputTokens, thinkingConfig, responseMimeType (text/plain ou application/json), responseSchema ou responseJsonSchema (objeto JSON), stopSequences (array de cadeias de caracteres), candidateCount: 1, um inteiro seed, os valores numéricos presencePenalty e frequencyPenalty. Os intervalos e as capacidades permitidos dependem do modelo exato; para uma resposta JSON, escolha uma forma de esquema suportada e application/json. Nos modelos de texto, responseModalities — apenas ["TEXT"].
  • safetySettings — array de objetos com category, threshold e o campo opcional method; escolha os valores de acordo com a documentação do modelo exato.
  • Nos modelos Gemini que suportam o tipo de entrada correspondente, parts[].inlineData contém mimeType e dados base64 não vazios; o PDF tem de ser um PDF válido. fileData contém um endereço público httpsno campo fileUri e 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 acrescentar videoMetadata: startOffset/endOffset como cadeia de caracteres em segundos (por exemplo, 1.5s) e fps superior 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 functionDeclarations do cliente são executadas pela sua aplicação. Os modelos de texto também aceitam {"googleSearch": {}} e {"urlContext": {}}: em separado ou em conjunto no array tools. Nem Google Search nem URL context podem ser combinados com functionDeclarations no 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 de toolUsePromptTokenCount sã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 400 com status INVALID_ARGUMENT e a classe invalid_request (em ErrorInfo.reason — INVALID_REQUEST). JSON inválido, erros nos parâmetros do caminho e noutras validações também devolvem 400; leia o texto do erro e o Request ID. As capacidades dependem do modelo: consulte os seus formatos e entradas no catálogo.
EntradaTipos MIME suportados
Imagens inlineimage/png, image/jpeg, image/webp
Documentosapplication/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
Áudioaudio/wav, audio/mp3, audio/mpeg, audio/aiff, audio/aac, audio/ogg, audio/flac
Vídeovideo/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)

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.

Ainda tem dúvidas? Envie o Request ID e uma descrição — ajudamos a esclarecer.Contactar o suporte