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

# Web search na Responses API

> Dê aos modelos acesso a informações atuais da web pela Responses API, com web search integrado na OpenAI, na Anthropic e no Google.

**Casos de uso**

* Responder a perguntas sobre eventos posteriores à data de corte do treinamento do modelo.
* Fundamentar respostas em dados em tempo real (preços, disponibilidade, notícias de última hora).
* Assistentes de pesquisa que precisam citar fontes verificáveis e atualizadas.
* Bots de suporte ao cliente que consultam a documentação ou as políticas atuais no momento da consulta.

***

## Visão geral

Use **`POST /responses`** no AI Gateway com o mesmo formato de solicitação da [OpenAI Responses API](https://developers.openai.com/api/reference/responses/overview): `model`, `input` e um array `tools` que inclua uma entrada de web search integrado. O **AI Gateway** encaminha a pesquisa para o recurso nativo de cada provedor quando o modelo oferece suporte a ele. Consulte [Responses API](/docs/pt-BR/ai-gateway/features/responses-api.md) para ter uma visão geral do endpoint e saber quando escolhê-lo em vez de Chat Completions.

Não há uma ferramenta separada do Perplexity ou do Parallel no **AI Gateway**; o contrato compatível são as ferramentas `web_search` / `web_search_preview` **no estilo da OpenAI** em `/responses`, mapeadas para a Anthropic e o Google quando aplicável.

> [!NOTE]
>
> Prefira modelos cujos metadados indiquem suporte a web search. Consulte [Modelos compatíveis](/docs/pt-BR/ai-gateway/supported-models.md) e a lista de modelos do workspace.

### Outras formas de pesquisar

Chat Completions acessa o web search por um contrato diferente, executado pelo gateway: a [ferramenta de servidor `orq:web_search`](/docs/pt-BR/ai-gateway/features/server-tools/web-search), em que o **AI Gateway** executa cada pesquisa e retorna os resultados ao modelo, configurada com `max_results`, `max_uses`, `engine` e `allowed_domains` / `excluded_domains`.

## Início rápido

Use o SDK da OpenAI com a URL base do AI Gateway e chame a Responses API diretamente.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://router.toqan.ai/eu/v3/router/responses" \
  -H "Authorization: Bearer ${TOQAN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What are the latest changes to the OpenAI Responses API?",
    "tools": [{ "type": "web_search_preview" }]
  }'
```

```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: "openai/gpt-5.6-sol",
  input: "What are the latest changes to the OpenAI Responses API?",
  tools: [{ type: "web_search_preview" }],
});

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="openai/gpt-5.6-sol",
    input="What are the latest changes to the OpenAI Responses API?",
    tools=[{"type": "web_search_preview"}],
)

print(response.output_text)
```

Endpoint:

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

## Definições de ferramentas

As entradas de `tools` da solicitação usam o campo discriminador **`type`**, de acordo com o schema do gateway.

### `web_search_preview`

| Campo | Tipo | Descrição |
| - | - | - |
| `type` | `"web_search_preview"` | Identifica a ferramenta de web search em versão preview. |
| `domains` | string\[] | Lista opcional de domínios permitidos para restringir a pesquisa. |
| `search_context_size` | string | Opcional. Um entre `low`, `medium`, `high`. Controla quanto contexto é recuperado por resultado. |
| `user_location` | object | Opcional. Indicações para resultados localizados (`type`, `city`, `country`, `region`, `timezone`). |

### `web_search`

| Campo | Tipo | Descrição |
| - | - | - |
| `type` | `"web_search"` | Tipo estável da ferramenta de web search. |
| `search_context_size` | string | Opcional. `low`, `medium`, `high`. |
| `user_location` | object | Opcional. Mesmo formato descrito acima. |
| `filters` | object | Opcional. Por exemplo, `allowed_domains` (array anulável) para restringir domínios. |

> [!WARNING]
>
> O **AI Gateway** aceita o objeto completo da ferramenta em `/responses`. As solicitações para a **OpenAI** repassam as ferramentas para a Responses API upstream. Os caminhos da **Anthropic** e do **Google** mapeiam `web_search` / `web_search_preview` para as ferramentas nativas de web search; campos não compatíveis com a API upstream podem ser ignorados.

## `include` (opcional)

Você pode solicitar campos adicionais nos itens de saída do web search, de acordo com o `include` da OpenAI Responses:

| Valor | Significado |
| - | - |
| `web_search_call.results` | Inclui resultados de pesquisa detalhados, quando disponíveis. |
| `web_search_call.action.sources` | Inclui URLs e títulos das fontes na ação. |

Exemplo de corpo da solicitação:

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "openai/gpt-5.6-sol",
  "input": "Summarize today’s headlines in finance.",
  "tools": [{ "type": "web_search_preview" }],
  "include": ["web_search_call.action.sources"]
}
```

## Saída: `web_search_call`

As respostas podem conter itens de saída com `"type": "web_search_call"`:

| Campo | Descrição |
| - | - |
| `id` | ID do item. |
| `type` | `"web_search_call"`. |
| `status` | Status do ciclo de vida da chamada. |
| `action` | Opcional. `type` pode ser `search`, `open_page` ou `find`, além de campos como `query`, `url`, `pattern` e `sources` (url + título). |

O formato exato do payload corresponde ao que o provedor retorna; o streaming usa o mesmo modelo de eventos dos outros streams de `/responses`.

## Comportamento dos provedores

### OpenAI

Envie `tools` e `include` no corpo da solicitação com o ID do modelo (por exemplo, `openai/gpt-5.6-sol`). Use os mesmos parâmetros que a OpenAI documenta para [web search](https://platform.openai.com/docs/guides/tools-web-search) na Responses API.

> [card] [OpenAI](/docs/pt-BR/ai-studio/integrations/providers/openai.md)
>
> Configure sua chave de API da OpenAI para usar o GPT-5.6 Sol com web search.

### Anthropic

`web_search` e `web_search_preview` em `tools` são mapeados para a ferramenta de web search da Anthropic no caminho Messages usado em `/responses`.

> [card] [Anthropic](/docs/pt-BR/ai-studio/integrations/providers/anthropic.md)
>
> Configure sua chave de API da Anthropic para usar o Claude com web search.

### Google Gemini

Os mesmos tipos de ferramenta habilitam o **Google Search grounding** (`googleSearch`) nos modelos Gemini compatíveis.

> [card] [Google AI](/docs/pt-BR/ai-studio/integrations/providers/google-ai.md)
>
> Configure sua chave de API do Google AI para usar os modelos Gemini com Google Search grounding.

## `tool_choice`

Você pode direcionar o modelo para o web search usando a forma estruturada de `tool_choice`, por exemplo:

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "tool_choice": { "type": "web_search_preview" }
}
```

Os valores de `tool_choice.type` compatíveis com ferramentas integradas são definidos no schema da API (incluindo `web_search`, `web_search_preview` e literais relacionados). As strings `none`, `auto` e `required` funcionam normalmente.

## Streaming

Defina **`"stream": true`** no mesmo corpo JSON. O servidor responde com **`text/event-stream`** e eventos no formato de stream de resposta no estilo da OpenAI.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -N -X POST "https://router.toqan.ai/eu/v3/router/responses" \
  -H "Authorization: Bearer ${TOQAN_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What is the current phase of the moon for San Francisco?",
    "tools": [{ "type": "web_search_preview" }],
    "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: "openai/gpt-5.6-sol",
  input: "What is the current phase of the moon for San Francisco?",
  tools: [{ type: "web_search_preview" }],
  stream: true,
});

for await (const event of stream) {
  console.log(event);
}
```

```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="openai/gpt-5.6-sol",
    input="What is the current phase of the moon for San Francisco?",
    tools=[{"type": "web_search_preview"}],
    stream=True,
)

for event in stream:
    print(event)
```

> [!NOTE]
>
> No streaming com cURL, `-N` desativa o buffer para que as linhas SSE apareçam à medida que chegam. Analise as linhas `data:` do corpo da resposta da mesma forma que faria com o stream da Responses da OpenAI.

## Exemplos de código

Defina **`TOQAN_API_KEY`** (ou passe a chave explicitamente) para que o cabeçalho `Authorization` seja resolvido.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "https://router.toqan.ai/eu/v3/router/responses" \
  -H "Authorization: Bearer ${TOQAN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What is the current phase of the moon for San Francisco?",
    "tools": [{ "type": "web_search_preview" }],
    "include": ["web_search_call.action.sources"]
  }'
```

```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: "openai/gpt-5.6-sol",
  input: "What is the current phase of the moon for San Francisco?",
  tools: [{ type: "web_search_preview" }],
  include: ["web_search_call.action.sources"],
});

console.log(response.output_text);

for (const item of response.output ?? []) {
  if (item.type === "web_search_call") {
    console.log("web_search_call", item.action);
  }
}
```

```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="openai/gpt-5.6-sol",
    input="What is the current phase of the moon for San Francisco?",
    tools=[{"type": "web_search_preview"}],
    include=["web_search_call.action.sources"],
)

print(response.output_text)

for item in response.output or []:
    if item.type == "web_search_call":
        print("web_search_call", item.action)
```

## Veja também

* [Responses API](/docs/pt-BR/ai-gateway/features/responses-api.md): o endpoint em que o web search é executado e quando escolhê-lo em vez de Chat Completions
* [API compatível com OpenAI](/docs/pt-BR/ai-gateway/features/openai-compatible-api.md): URL base e `/responses`
* [Raciocínio](/docs/pt-BR/ai-gateway/features/reasoning.md): `reasoning` para modelos da OpenAI pela Responses API; `thinking` para Anthropic e Google Gemini por Chat Completions
* [Chamada de ferramentas](/docs/pt-BR/ai-gateway/features/tool-calling.md): ferramentas de função em `/chat/completions` e `/responses`
* [Ferramenta de servidor Web search](/docs/pt-BR/ai-gateway/features/server-tools/web-search.md): o contrato `orq:web_search` executado pelo gateway em Chat Completions


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