> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Vertex AI

> Conecte o Google Vertex AI ao Toqan Router para ter acesso corporativo ao Gemini. Configure a autenticação por conta de serviço, o faturamento por projeto e os controles de residência de dados.

O Google Vertex AI oferece acesso de nível corporativo aos modelos Gemini, com mais segurança, conformidade e controle. Ao conectar o Vertex AI ao Toqan Router, você obtém os recursos corporativos do Gemini com autenticação por conta de serviço, faturamento no nível do projeto e controles de residência de dados.

## Configure sua chave de API

Para usar o Vertex AI com o Toqan Router, você precisa criar uma conta de serviço com as permissões adequadas:

**1. Criar a conta de serviço**

1. Acesse o [Google Cloud Console](https://console.cloud.google.com)
2. Navegue até **IAM & Admin** > **Service Accounts**
3. Clique em **Create Service Account**
4. Insira um nome (por exemplo, "toqan-vertex-ai")
5. Conceda os seguintes papéis:
   * **Service Account Token Creator**
   * **Vertex AI User**
6. Clique em **Create and Continue**
7. Clique em **Done**

**2. Criar a chave da conta de serviço**

1. Encontre sua conta de serviço na lista
2. Clique no menu **Actions** (três pontos)
3. Selecione **Manage Keys**
4. Clique em **Add Key** > **Create New Key**
5. Selecione o formato **JSON**
6. Clique em **Create** para baixar o arquivo da chave

**3. Configurar no Toqan Router**

1. Navegue até **AI Gateway** > BYOK
2. Encontre **Google Vertex AI** na lista
3. Clique no botão **Configure**
4. Selecione <kbd>Setup your own API Key</kbd>
5. Insira o nome da configuração (por exemplo, "Vertex AI Production")
6. Monte o **Deployment JSON** no formato abaixo: defina `projectId` e `location` e cole a chave da conta de serviço baixada como valor de `serviceAccount`
7. Clique em **Save** para concluir a configuração

### Formato do Deployment JSON

O Deployment JSON deve incluir as credenciais da conta de serviço, o ID do projeto e a região:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "projectId": "my-project-123456",
  "location": "us-central1",
  "serviceAccount": {
    "type": "service_account",
    "project_id": "my-project-123456",
    "private_key_id": "afd17083ecd5184b5ca880e70eb84c2e4c382f14",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...=\n-----END PRIVATE KEY-----\n",
    "client_email": "vertex-ai@my-project-123456.iam.gserviceaccount.com",
    "client_id": "000000000000000000000",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/vertex-ai%40my-project-123456.iam.gserviceaccount.com",
    "universe_domain": "googleapis.com"
  }
}
```

> [!NOTE]
>
> **Project ID**: encontre o ID do seu projeto do Google Cloud na parte superior do Google Cloud Console.
>
> **Location**: regiões comuns incluem `us-central1`, `europe-west1` e `asia-northeast1`. Escolha de acordo com seus requisitos de residência de dados.

## Modelos disponíveis

O **AI Gateway** é compatível com todos os modelos Gemini atuais do Vertex AI. Estes são os mais usados:

### Modelos recomendados

| Modelo | Contexto | Ideal para |
| - | - | - |
| `google/gemini-3.1-pro-preview` | 1M | Prévia mais recente, o mais avançado |
| `google/gemini-2.5-pro` | 1M | Estável, alta capacidade |
| `google/gemini-3.5-flash` | 1M | Rápido, desempenho equilibrado |

Para ver uma lista completa e atualizada de todos os modelos do Vertex AI disponíveis, consulte [Modelos compatíveis](/docs/pt-BR/ai-gateway/supported-models.md#chat-models).

> [!TIP]
>
> Use `google/gemini-2.5-pro` para um modelo estável e de alta capacidade ou `google/gemini-3.5-flash` para o melhor equilíbrio entre desempenho e custo.

## Início rápido

Acesse os modelos Gemini do Vertex AI por meio do **AI Gateway**.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-pro",
    "input": "Explain quantum computing in simple terms"
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "google/gemini-2.5-pro",
  input: "Explain quantum computing in simple terms",
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="google/gemini-2.5-pro",
    input="Explain quantum computing in simple terms",
)

print(response.output_text)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "google/gemini-2.5-pro",
  messages: [{ role: "user", content: "Explain quantum computing in simple terms" }],
});

console.log(response.choices[0].message.content);
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="google/gemini-2.5-pro",
    messages=[{"role": "user", "content": "Explain quantum computing in simple terms"}],
)

print(response.choices[0].message.content)
```

## Usando o AI Gateway

Acesse os modelos Gemini do Vertex AI por meio do **AI Gateway** com segurança de nível corporativo, chat completions avançados, streaming e roteamento inteligente de modelos. Todos os modelos do Vertex AI estão disponíveis com formatação consistente e registro automático de solicitações.

> [!NOTE]
>
> Os modelos do Vertex AI usam o formato de slug de provedor: `google/model-name`. Por exemplo: `google/gemini-2.5-pro`

### Pré-requisitos

Antes de fazer solicitações ao **AI Gateway**, você precisa configurar seu ambiente e instalar os SDKs, caso opte por usá-los.

**Endpoint**

```
POST https://router.toqan.ai/eu/v3/router/responses
```

**Headers obrigatórios**

Inclua os seguintes headers em todas as solicitações:

```
Authorization: Bearer $TOQAN_API_KEY
Content-Type: application/json
```

**Obtendo sua chave de API:**

1. Acesse Chaves de API
2. Clique em <kbd>Create API Key</kbd> e copie a chave
3. Armazene-a no seu ambiente como `TOQAN_API_KEY`

**Instalação do SDK**

Instale o SDK da OpenAI para a sua linguagem (compatível com os modelos do Vertex AI):

```bash Node.js/TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install openai
# or
yarn add openai
```

```bash Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install openai
```

> [!TIP]
>
> Se o seu código da OpenAI já estiver funcionando, basta alterar `base_url` e `api_key` para o endpoint do router e `TOQAN_API_KEY`.

### Uso básico

Envie mensagens aos modelos Gemini do Vertex AI e obtenha respostas inteligentes:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-pro",
    "instructions": "You are a helpful assistant that explains complex concepts simply.",
    "input": "Explain machine learning"
  }'
```

```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-pro",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant that explains complex concepts simply."},
      {"role": "user", "content": "Explain machine learning"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "google/gemini-2.5-pro",
  instructions: "You are a helpful assistant that explains complex concepts simply.",
  input: "Explain machine learning",
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="google/gemini-2.5-pro",
    instructions="You are a helpful assistant that explains complex concepts simply.",
    input="Explain machine learning",
)

print(response.output_text)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "google/gemini-2.5-pro",
  messages: [
    {
      role: "system",
      content: "You are a helpful assistant that explains complex concepts simply.",
    },
    { role: "user", content: "Explain machine learning" },
  ],
  temperature: 0.7,
  max_tokens: 500,
});

console.log(response.choices[0].message.content);
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="google/gemini-2.5-pro",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant that explains complex concepts simply.",
        },
        {"role": "user", "content": "Explain machine learning"},
    ],
    temperature=0.7,
    max_tokens=500,
)

print(response.choices[0].message.content)
```

### Streaming

Faça streaming das respostas para obter saída em tempo real e uma melhor experiência do usuário:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-pro",
    "input": "Write a short poem about the ocean",
    "stream": true
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const stream = await client.responses.create({
  model: "google/gemini-2.5-pro",
  input: "Write a short poem about the ocean",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

stream = client.responses.create(
    model="google/gemini-2.5-pro",
    input="Write a short poem about the ocean",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const stream = await client.chat.completions.create({
  model: "google/gemini-2.5-pro",
  messages: [{ role: "user", content: "Write a short poem about the ocean" }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || "";
  process.stdout.write(content);
}
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

stream = client.chat.completions.create(
    model="google/gemini-2.5-pro",
    messages=[{"role": "user", "content": "Write a short poem about the ocean"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

### Chamada de funções

Os modelos Gemini do Vertex AI oferecem suporte a chamada de funções para interações estruturadas:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.responses.create({
  model: "google/gemini-2.5-pro",
  input: "What's the weather in San Francisco?",
  tools: [
    {
      type: "function",
      name: "get_weather",
      description: "Get the current weather in a location",
      parameters: {
        type: "object",
        properties: {
          location: {
            type: "string",
            description: "The city and state, e.g. San Francisco, CA",
          },
          unit: { type: "string", enum: ["celsius", "fahrenheit"] },
        },
        required: ["location"],
      },
    },
  ],
});

const toolCall = response.output.find((item) => item.type === "function_call");
if (toolCall && toolCall.type === "function_call") {
  console.log(`Calling function: ${toolCall.name}`);
  console.log(`Arguments: ${toolCall.arguments}`);
}
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="google/gemini-2.5-pro",
    input="What's the weather in San Francisco?",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get the current weather in a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
        }
    ],
)

tool_call = next((item for item in response.output if item.type == "function_call"), None)
if tool_call:
    print(f"Calling function: {tool_call.name}")
    print(f"Arguments: {tool_call.arguments}")
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const response = await client.chat.completions.create({
  model: "google/gemini-2.5-pro",
  messages: [{ role: "user", content: "What's the weather in San Francisco?" }],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Get the current weather in a location",
        parameters: {
          type: "object",
          properties: {
            location: {
              type: "string",
              description: "The city and state, e.g. San Francisco, CA",
            },
            unit: { type: "string", enum: ["celsius", "fahrenheit"] },
          },
          required: ["location"],
        },
      },
    },
  ],
});

const choice = response.choices[0];
if (choice.finish_reason === "tool_calls" && choice.message.tool_calls) {
  const toolCall = choice.message.tool_calls[0];
  console.log(`Calling function: ${toolCall.function.name}`);
  console.log(`Arguments: ${toolCall.function.arguments}`);
}
```

```python Python (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="google/gemini-2.5-pro",
    messages=[{"role": "user", "content": "What's the weather in San Francisco?"}],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get the current weather in a location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA",
                        },
                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                    },
                    "required": ["location"],
                },
            },
        }
    ],
)

choice = response.choices[0]
if choice.finish_reason == "tool_calls" and choice.message.tool_calls:
    tool_call = choice.message.tool_calls[0]
    print(f"Calling function: {tool_call.function.name}")
    print(f"Arguments: {tool_call.function.arguments}")
```

## Registro automático de solicitações

Todas as solicitações feitas por meio do **AI Gateway** são registradas automaticamente no seu painel. Você pode ver:

* **Detalhes da solicitação**: modelo usado, tokens, latência
* **Acompanhamento de custos**: custos por solicitação e agregados
* **Monitoramento de erros**: solicitações com falha e mensagens de erro
* **Métricas de desempenho**: tempos de resposta e throughput

Nenhuma configuração adicional é necessária. O registro acontece automaticamente.

## Referência

* [Documentação do Vertex AI](https://cloud.google.com/vertex-ai/docs)
* [Referência da API do Gemini](https://ai.google.dev/api/generate-content)
* [Configuração de contas de serviço](https://cloud.google.com/iam/docs/service-accounts-create)
* [Preços do Vertex AI](https://cloud.google.com/vertex-ai/pricing)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.