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

# Web Search

export const OpenAIApiResponse = ({successJson, successTitle = "200 - Success", streaming = false}) => {
  const error400 = `{
    "error": {
        "code": "invalid_params",
        "message": "parameter 'ARGUMENT' is required",
        "param": null,
        "type": "invalid_request_error"
    }
}`;
  const error401 = `{
    "error": {
        "code": "auth_invalid",
        "message": "Invalid API Key",
        "param": null,
        "type": "authentication_error"
    }
}`;
  const error402 = `{
    "error": {
        "code": "insufficient_quota",
        "message": "You exceeded your current quota, please check your plan and billing details.",
        "param": null,
        "type": "insufficient_quota_error"
    }
}`;
  const error403 = `{
    "error": {
        "code": "permission_error",
        "message": "You have no permission to access the model.",
        "type": "permission_error",
        "param": null
    }
}`;
  const error404 = `{
    "error": {
        "code": "invalid_request_error",
        "message": "Invalid URL",
        "param": null,
        "type": "invalid_request_error"
    }
}`;
  const error429 = `{
    "error": {
        "code": "rate_limit_exceeded",
        "message": "Rate limit reached",
        "param": null,
        "type": "rate_limit_error"
    }
}`;
  const error500 = `{
    "error": {
        "code": "server_error",
        "message": "Internal server error",
        "param": null,
        "type": "server_error"
    }
}`;
  return <>
      <h2>Response Examples</h2>

      <CodeGroup>
        <CodeBlock language={streaming ? "text" : "json"} filename={streaming ? "200 - Streaming Response (SSE)" : successTitle}>
          {successJson}
        </CodeBlock>
        <CodeBlock language="json" filename="400 - Bad Request">
          {error400}
        </CodeBlock>
        <CodeBlock language="json" filename="401 - Unauthorized">
          {error401}
        </CodeBlock>
        <CodeBlock language="json" filename="402 - Insufficient Balance">
          {error402}
        </CodeBlock>
        <CodeBlock language="json" filename="403 - Permission Denied">
          {error403}
        </CodeBlock>
        <CodeBlock language="json" filename="404 - Invalid URL">
          {error404}
        </CodeBlock>
        <CodeBlock language="json" filename="429 - Too Many Requests">
          {error429}
        </CodeBlock>
        <CodeBlock language="json" filename="500 - Internal Server Error">
          {error500}
        </CodeBlock>
      </CodeGroup>
    </>;
};

export const OpenAIWebSearch = ({model = "gpt-4.1"}) => {
  const curlExample = `curl --request POST \\
  --url https://aiandgpu.com/v1/responses \\
  --header 'Authorization: Bearer <YOUR_API_KEY>' \\
  --header 'Content-Type: application/json' \\
  --data '{
    "model": "${model}",
    "tools": [
      {
        "type": "web_search_preview"
      }
    ],
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Introduce about Elon Mask's starlink?"
          }
        ]
      }
    ]
  }'`;
  const pythonExample = `import requests

url = "https://aiandgpu.com/v1/responses"

payload = {
    "model": "${model}",
    "tools": [
        {
            "type": "web_search_preview"
        }
    ],
    "input": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Introduce about Elon Mask's starlink?"
                }
            ]
        }
    ]
}

headers = {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json",
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())`;
  const jsExample = `const response = await fetch('https://aiandgpu.com/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '${model}',
    tools: [
      {
        type: 'web_search_preview'
      }
    ],
    input: [
      {
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'Introduce about Elon Mask's starlink?'
          }
        ]
      }
    ]
  })
});

const data = await response.json();
console.log(data);`;
  const goExample = `package main

import (
\t"fmt"
\t"io"
\t"net/http"
\t"strings"
)

func main() {
\turl := "https://aiandgpu.com/v1/responses"

\tpayload := strings.NewReader(\`{
\t\t"model": "${model}",
\t\t"tools": [{"type": "web_search_preview"}],
\t\t"input": [{"role": "user", "content": [{"type": "input_text", "text": "Introduce about Elon Mask's starlink?"}]}]
\t}\`)

\treq, _ := http.NewRequest("POST", url, payload)

\treq.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
\treq.Header.Add("Content-Type", "application/json")

\tres, _ := http.DefaultClient.Do(req)
\tdefer res.Body.Close()

\tbody, _ := io.ReadAll(res.Body)
\tfmt.Println(string(body))
}`;
  const javaExample = `import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

String body = """
{
  "model": "${model}",
  "tools": [{"type": "web_search_preview"}],
  "input": [
    {
      "role": "user",
      "content": [{"type": "input_text", "text": "Introduce about Elon Mask's starlink?"}]
    }
  ]
}
""";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://aiandgpu.com/v1/responses"))
    .header("Authorization", "Bearer <YOUR_API_KEY>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());`;
  const phpExample = `<?php

$curl = curl_init();

$payload = json_encode([
    'model' => '${model}',
    'tools' => [
        ['type' => 'web_search_preview']
    ],
    'input' => [
        [
            'role' => 'user',
            'content' => [
                ['type' => 'input_text', 'text' => 'Introduce about Elon Mask's starlink?']
            ]
        ]
    ]
]);

curl_setopt_array($curl, [
    CURLOPT_URL => "https://aiandgpu.com/v1/responses",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer <YOUR_API_KEY>",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;`;
  const csharpExample = `using System.Net.Http;
using System.Text;

var client = new HttpClient();

var payload = @"{
    ""model"": ""${model}"",
    ""tools"": [{""type"": ""web_search_preview""}],
    ""input"": [
        {
            ""role"": ""user"",
            ""content"": [{""type"": ""input_text"", ""text"": ""Introduce about Elon Mask's starlink?""}]
        }
    ]
}";

var request = new HttpRequestMessage(HttpMethod.Post, "https://aiandgpu.com/v1/responses");
request.Headers.Add("Authorization", "Bearer <YOUR_API_KEY>");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);`;
  return <>
      <h2>Request Examples</h2>

      <CodeGroup>
        <CodeBlock language="shellscript" filename="cURL">
          {curlExample}
        </CodeBlock>
        <CodeBlock language="python" filename="Python">
          {pythonExample}
        </CodeBlock>
        <CodeBlock language="javascript" filename="JavaScript">
          {jsExample}
        </CodeBlock>
        <CodeBlock language="go" filename="Go">
          {goExample}
        </CodeBlock>
        <CodeBlock language="java" filename="Java">
          {javaExample}
        </CodeBlock>
        <CodeBlock language="php" filename="PHP">
          {phpExample}
        </CodeBlock>
        <CodeBlock language="csharp" filename="C#">
          {csharpExample}
        </CodeBlock>
      </CodeGroup>
    </>;
};

## Authorization

* **Auth Type**: `Bearer Auth` (In: `header`)
* **Format**: `Authorization: Bearer <YOUR_API_KEY>`
* **Description**: Use `Bearer <YOUR_API_KEY>`. Format: `Authorization: Bearer sk-xxxxxx.`
* **API Key**: where <strong>API Key</strong> is your <a href="https://developer.aiandgpu.com" target="_blank" rel="noopener noreferrer">AGCloud API KEY</a>

<OpenAIWebSearch model="gpt-4o-mini-2024-07-18" />

<OpenAIApiResponse
  successJson={`{
"id": "resp_04826d893205e1a30069afc682f8b081938da0673685c1b2e2",
"object": "response",
"created_at": 1773127298,
"status": "completed",
"background": false,
"completed_at": 1773127304,
"content_filters": [],
"error": null,
"frequency_penalty": 0.0,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"max_tool_calls": null,
"model": "gpt-4.1-global",
"output": [
    {
        "id": "msg_04826d893205e1a30069afc6842c6481939254cb63969bee01",
        "type": "message",
        "status": "completed",
        "content": [
            {
                "type": "output_text",
                "annotations": [],
                "logprobs": [],
                "text": "Starlink is a satellite internet constellation project developed by SpaceX, the aerospace company founded by Elon Musk. Starlink aims to provide high-speed, broadband internet access to underserved and remote areas around the world using a network of low Earth orbit (LEO) satellites. The main advantages of Starlink include:\n\n- **Global Coverage:** Starlink seeks to offer internet service in places where traditional fiber or cable connections are unavailable or unreliable.\n- **High Speed & Low Latency:** The constellation of LEO satellites enables faster data transmission and lower latency compared to traditional geostationary satellites.\n- **Rapid Deployment:** No ground-based infrastructure is needed, making it quick to roll out services to new areas.\n\nStarlink began its public beta in 2020 and has since expanded to cover millions of customers globally. It is especially beneficial for rural communities, remote offices, and locations affected by natural disasters, playing a role in bridging the global digital divide. Starlink also has applications for moving vehicles, such as ships and airplanes.\n\nAs of 2024, Starlink had launched over 5,000 satellites and continues its expansion, further solidifying SpaceX’s position as a leader in satellite internet technology [SpaceX: Starlink](https://www.spacex.com/updates/starlink-update-04-2022/)."
            }
        ],
        "role": "assistant"
    }
],
"parallel_tool_calls": true,
"presence_penalty": 0.0,
"previous_response_id": null,
"prompt_cache_key": null,
"prompt_cache_retention": null,
"reasoning": {
    "effort": null,
    "summary": null
},
"safety_identifier": null,
"service_tier": "default",
"store": true,
"temperature": 1.0,
"text": {
    "format": {
        "type": "text"
    },
    "verbosity": "medium"
},
"tool_choice": "auto",
"tools": [
    {
        "type": "web_search_preview",
        "search_context_size": "medium",
        "user_location": {
            "type": "approximate",
            "city": null,
            "country": "US",
            "region": null,
            "timezone": null
        }
    }
],
"top_logprobs": 0,
"top_p": 1.0,
"truncation": "disabled",
"usage": {
    "input_tokens": 326,
    "input_tokens_details": {
        "cached_tokens": 0
    },
    "output_tokens": 267,
    "output_tokens_details": {
        "reasoning_tokens": 0
    },
    "total_tokens": 593
},
"user": null,
"metadata": {}
}`}
/>

## Request Body

### Core Parameters

| Field            | Type                    | Required | Range                                                        | Description                                                                                                                                                             |
| :--------------- | :---------------------- | :------- | :----------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`          | `string`                | ✅        | -                                                            | Model ID used to generate the response.                                                                                                                                 |
| `input`          | `array<object>`         | ✅        | -                                                            | The input content.                                                                                                                                                      |
| `>input.role`    | `enum`                  | ✅        | `user` <br /> `assistant` <br /> `system` <br /> `developer` | The role of the message sender. Can be `user` `model`.                                                                                                                  |
| `>input.content` | `string\|array<object>` | ✅        | -                                                            | A text input to the model when string; a list of one or many input items to the model, containing different content types when array. See Multimodal Input for details. |

### Content Structure

| Field       | Type     | Required | Range                                                  | Description                                                                                                                                                |
| :---------- | :------- | :------- | :----------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`      | `string` | ✅        | `input_text` <br /> `input_image` <br />  `input_file` | Identifies the content block type for multimodal input.                                                                                                    |
| `text`      | `string` | -        | -                                                      | The text input content.                                                                                                                                    |
| `file_id`   | `string` | -        | -                                                      | The ID of the file to be sent to the model.                                                                                                                |
| `detail`    | `string` | -        | `low` <br /> `high` <br /> `auto`                      | The detail level of the image to be sent to the model. One of high, low, or auto. Defaults to auto. Only required when `type=input_image`. Default `auto`. |
| `image_url` | `string` | -        | -                                                      | The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. Only required when `type=input_image`.          |
| `file_url`  | `string` | -        | -                                                      | The URL of the file to be sent to the model. Only required when `type=input_file`.                                                                         |
| `file_data` | `string` | -        | -                                                      | The content of the file to be sent to the model. Only required when `type=input_file`.                                                                     |
| `filename`  | `string` | -        | -                                                      | The name of the file to be sent to the model. Only required when `type=input_file`.                                                                        |

<CodeGroup>
  ```json Text Input theme={null}
  {
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Who are you?"
      }
    ]
  }
  ```

  ```json Image Input theme={null}
  {
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Describe this image."
      },
      {
        "type": "input_image",
        "image_url": "https://robohash.org/OYK.png"
      }
    ]
  }
  ```

  ```json File Input theme={null}
  {
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "summary this pdf file."
      },
      {
        "type": "input_file",
        "file_url": "https://pdfobject.com/pdf/sample.pdf"
      }
    ]
  }
  ```
</CodeGroup>

### Advanced Parameters

| Field                | Type            | Required | Range                                                                             | Description                                                                                                                                                                                                |
| :------------------- | :-------------- | :------- | :-------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stream`             | `boolean`       | -        | -                                                                                 | Whether to stream the response back incrementally. Defaults `false`.                                                                                                                                       |
| `max_output_tokens`  | `internet`      | -        | -                                                                                 | An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.                                                                        |
| `reasoning`          | `object`        | -        | -                                                                                 | Configuration options for reasoning models (gpt-5 and o-series models only).                                                                                                                               |
| `>reasoning.effort`  | `enum`          | -        | `none` <br /> `minimal` <br /> `low` <br /> `medium` <br /> `high` <br /> `xhigh` | Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning. See Model-Specific Reasoning Configurations for details. |
| `>reasoning.summary` | `enum`          | -        | `auto` <br /> `concise` <br /> `detailed`                                         | A summary of the reasoning performed by the model. Useful for debugging and understanding the model’s reasoning process.                                                                                   |
| `tools`              | `array<object>` | -        | -                                                                                 | A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. See Tools Parameters for details.   |

### Tools Parameters

```json theme={null}
{
  "tools": [
    {
      "type": "web_search",
      "filters": {
        "allowed_domains": ["example.com"]
      },
      "search_context_size": "low",
      "user_location": {
        "city": "San Francisco",
        "country": "US",
        "region": "California",
        "timezone": "America/Los_Angeles",
        "type": "approximate"
      }
    }
  ]
}
```

| Field                     | Type            | Required | Range                                       | Description                                                                                                                           |
| :------------------------ | :-------------- | :------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------ |
| `type`                    | `enum`          | -        | `web_search` <br /> `web_search_2025_08_26` | The type of the web search tool.                                                                                                      |
| `filter`                  | `object`        | -        | -                                           | Filters for the search.                                                                                                               |
| `>filter.allowed_domains` | `array<string>` | -        | -                                           | Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well.     |
| `search_context_size`     | `enum`          | -        | `low` <br /> `medium` <br /> `high`         | High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default. |
| `user_location`           | `object`        | -        | -                                           | The approximate location of the user.                                                                                                 |
| `>user_location.city`     | `string`        | -        | -                                           | Free text input for the city of the user, e.g. San Francisco.                                                                         |
| `>user_location.country`  | `string`        | -        | -                                           | The two-letter ISO country code of the user, e.g. US.                                                                                 |
| `>user_location.region`   | `string`        | -        | -                                           | Free text input for the region of the user, e.g. California.                                                                          |
| `>user_location.timezone` | `string`        | -        | -                                           | The IANA timezone of the user, e.g. America/Los\_Angeles.                                                                             |
| `>user_location.type`     | `string`        | -        | `approximate`                               | The type of location approximation. Always `approximate`.                                                                             |

### Model-Specific Reasoning.effort Configurations

Constrains effort on reasoning for reasoning models. Currently supported values are none, minimal, low, medium, high, and xhigh. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.

* gpt-5.1 defaults to none, which does not perform reasoning. The supported reasoning values for gpt-5.1 are none, low, medium, and high. Tool calls are supported for all reasoning values in gpt-5.1.
* All models before gpt-5.1 default to medium reasoning effort, and do not support none.
* The gpt-5-pro model defaults to (and only supports) high reasoning effort.
* xhigh is supported for all models after gpt-5.1-codex-max.