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

[Ligação](https://ailoot.ai/docs/pt-pt/) 

# Google GenAI SDK

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

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

## [](https://ailoot.ai/docs/pt-pt/connect/google-genai/#install)Instalação

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

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

## [](https://ailoot.ai/docs/pt-pt/connect/google-genai/#client)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`.

```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"),  # sem /v1beta
)

resp = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Crie três nomes para um café.",
)
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" }, // 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);
```

```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": "Crie três nomes para um café."}]}
    ]
  }' 
```

## [](https://ailoot.ai/docs/pt-pt/connect/google-genai/#body)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 `https`no 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.

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

```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"},
    )
    # 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}}
```

## [](https://ailoot.ai/docs/pt-pt/connect/google-genai/#function-loop)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.

```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"},
    )
    # 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")
```

## [](https://ailoot.ai/docs/pt-pt/connect/google-genai/#stream)Resposta em fluxo

```python
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)
```

```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": "Descreva o pôr do sol sobre o mar"}]}]}' 
```

O Ailoot entrega a resposta paga do Gemini após o cálculo do custo: o texto do fluxo chega integralmente quando o modelo termina, e não palavra a palavra. O fluxo Gemini não inclui linhas de serviço, por isso, deixe uma margem no tempo limite do cliente para respostas longas.

## [](https://ailoot.ai/docs/pt-pt/connect/google-genai/#models)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](https://ailoot.ai/docs/pt-pt/connect/anthropic-sdk/).

Ainda tem dúvidas? Envie o Request ID e uma descrição — ajudamos a esclarecer.[Contactar o suporte](mailto:support@ailoot.ai)

## Ailoot · A empresa e a sua carteira de projetos





A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.





A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.





A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.