웹 검색 | OpenAI API

웹 검색을 사용하면 모델이 인터넷에서 최신 정보를 찾아 답변에 출처를 인용할 수 있습니다. 이 기능을 사용하려면 Responses API에서 웹 검색 도구를 활성화하세요. 일부 경우에는 Chat Completions에서도 웹 검색을 사용할 수 있습니다.

답하려는 질문에 맞춰 검색 워크플로우를 선택하세요.

특정 사실을 빠르게 확인하려면 모델에 해당 사실을 검색하고 출처를 인용해 달라고 요청하세요.
여러 출처를 참고해야 하는 질문에는 gpt-6-astra 같은 추론 모델을 사용하세요. 추론 모델은 검색 결과를 읽으면서 다음 검색을 구체화할 수 있습니다. 요청 처리에 몇 분이 걸릴 수 있다면 백그라운드 모드를 사용하세요.

통합 방식 선택

사용 사례	권장 방식	참고 사항
웹 검색을 새로 통합하는 경우	Responses API에서 `web_search`와 `gpt-6-astra` 사용	호스팅형 웹 검색에서 필터 설정, 출처 확인, 실시간 접근 제어, 장시간 리서치를 지원합니다.
기존 Chat Completions 검색 통합	Chat Completions에서 `gpt-5-search-api` 사용	기존 Chat Completions 통합을 유지해야 할 때만 사용하세요.
여러 단계의 리서치 또는 작성에 오래 걸리는 보고서	`gpt-6-astra`의 추론 수준을 `high` 또는 `xhigh`로 설정	보고서 작성에 몇 분이 걸릴 수 있다면 백그라운드 모드를 사용하세요.

Responses API에서는 콘텐츠 생성 요청의 tools 배열에 웹 검색 도구를 지정해 웹 검색을 활성화할 수 있습니다. 다른 도구와 마찬가지로 모델은 입력 프롬프트의 내용에 따라 웹 검색을 사용할지 결정합니다.

Responses API에 웹 검색을 새로 통합할 때는 { "type": "web_search" }를 사용하세요. 기존 통합에서는 이전 도구인 web_search_preview를 계속 사용할 수 있지만, 이 도구는 filters, external_web_access, return_token_budget 같은 최신 설정을 지원하지 않습니다.

웹 검색 도구 사용 예시

JavaScript

1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  tools: [{ type: "web_search" }],
  input: "What was a positive news story from today?",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    tools=[{"type": "web_search"}],
    input="What was a positive news story from today?",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{
			responses.ToolParamOfWebSearch(responses.WebSearchToolTypeWebSearch),
		},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What was a positive news story from today?")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.WebSearchTool;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("What was a positive news story from today?")
        .addTool(WebSearchTool.builder().type(WebSearchTool.Type.WEB_SEARCH).build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(ResponseTool.CreateWebSearchTool());
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("What was a positive news story from today?")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11require "openai"

openai = OpenAI::Client.new

response = openai.responses.create(
  model: "gpt-6-astra",
  tools: [{ type: "web_search" }],
  input: "What was a positive news story from today?"
)

puts(response.output_text)

1
2
3
4
5
6
7
8curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "tools": [{"type": "web_search"}],
        "input": "what was a positive news story from today?"
}'

1
2
3
4
5
6
7
8openai responses create \
  --model gpt-6-astra \
  --raw-output \
  --transform 'output.#(type=="message").content.0.text' <<'YAML'
tools:
  - type: web_search
input: What was a positive news story from today?
YAML

출력과 인용

웹 검색 도구를 사용한 모델 응답에는 두 가지 출력 항목이 포함됩니다.

web_search_call 출력 항목에는 검색 호출 ID가 들어 있으며, 수행한 작업은 web_search_call.action에 표시됩니다. 작업 유형은 다음 중 하나입니다.
- search는 웹 검색을 나타냅니다. 일반적으로 검색에 사용한 질의가 queries에 포함되지만 생략될 때도 있습니다. 검색 작업에는 도구 호출 비용이 발생합니다(요금 참고).
- open_page는 페이지를 여는 작업입니다. 추론 모델에서 지원합니다.
- find_in_page는 페이지 내에서 검색하는 작업입니다. 추론 모델에서 지원합니다.
message 출력 항목에는 다음이 포함됩니다.
- message.content[0].text에 담긴 텍스트 결과
- message.content[0].annotations에 담긴 인용 URL 주석

기본적으로 모델은 웹 검색 결과에서 찾은 URL을 응답 본문에 인용합니다. url_citation 주석 객체에는 인용한 출처의 URL과 제목, 응답 내 인용 위치가 들어 있습니다.

인터페이스에 웹 검색 결과나 그 결과에서 얻은 정보를 표시할 때는 본문에 인용한 출처를 클릭할 수 있는 링크로 눈에 잘 띄게 표시해야 합니다.

1234567891011121314151617181920212223242526272829303132[
  {
    "type": "web_search_call",
    "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",
    "status": "completed",
    "action": {
      "type": "search",
      "query": "latest news about AI"
    }
  },
  {
    "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "On March 6, 2025, several news...",
        "annotations": [
          {
            "type": "url_citation",
            "start_index": 2606,
            "end_index": 2758,
            "url": "https://...",
            "title": "Title..."
          }
        ]
      }
    ]
  }
]

Chat Completions API를 사용하면 ChatGPT 웹 검색에 쓰이는 파인튜닝된 모델과 도구를 직접 이용할 수 있습니다.

Chat Completions를 사용할 때 모델은 질의에 응답하기 전에 항상 웹에서 정보를 가져옵니다. 모델이 검색 여부를 결정하도록 하려면 Responses API로 전환하고 web_search 도구를 사용하세요.

현재 Chat Completions에서 웹 검색에 사용할 모델은 다음과 같습니다.

gpt-5-search-api

웹 검색 매개변수 사용 예시

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import OpenAI from "openai";
const client = new OpenAI();

const completion = await client.chat.completions.create({
  model: "gpt-5-search-api",
  web_search_options: {},
  messages: [
    {
      role: "user",
      content: "What was a positive news story from today?",
    },
  ],
});

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5-search-api",
    web_search_options={},
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?",
        }
    ],
)

print(completion.choices[0].message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model:            "gpt-5-search-api",
		WebSearchOptions: openai.ChatCompletionNewParamsWebSearchOptions{},
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("What was a positive news story from today?"),
		},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(completion.Choices[0].Message.Content)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-5-search-api")
        .addUserMessage("What was a positive news story today?")
        .webSearchOptions(ChatCompletionCreateParams.WebSearchOptions.builder().build())
        .build();

client.chat().completions().create(params).choices().stream()
    .flatMap(choice -> choice.message().content().stream())
    .forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11
12
13using OpenAI.Chat;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
string model = "gpt-5-search-api";
ChatClient client = new(model, key);

ChatCompletion completion = await client.CompleteChatAsync(
    [new UserChatMessage("What was a positive news story today?")],
    new ChatCompletionOptions { WebSearchOptions = new() }
);

Console.WriteLine(completion.Content[0].Text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15require "openai"

client = OpenAI::Client.new
completion = client.chat.completions.create(
  model: "gpt-5-search-api",
  messages: [
    {
      role: :user,
      content: "What was a positive news story today?"
    }
  ],
  web_search_options: {}
)

puts(completion.choices.fetch(0).message.content)

1
2
3
4
5
6
7
8
9
10
11curl -X POST "https://api.openai.com/v1/chat/completions" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-type: application/json" \
    -d '{
        "model": "gpt-5-search-api",
        "web_search_options": {},
        "messages": [{
            "role": "user",
            "content": "What was a positive news story from today?"
        }]
    }'

출력과 인용

choices 배열의 API 응답 항목에는 다음이 포함됩니다.

message.content에는 본문 인용을 포함한 모델의 텍스트 결과가 들어 있습니다.
annotations에는 인용한 URL 목록이 들어 있습니다.

기본적으로 모델은 웹 검색 결과에서 찾은 URL을 응답 본문에 인용합니다. url_citation 주석 객체에는 인용한 출처의 URL과 제목, 모델 응답에서 해당 출처를 사용한 구간의 시작 및 끝 문자 인덱스가 들어 있습니다.

인터페이스에 웹 검색 결과나 그 결과에서 얻은 정보를 표시할 때는 본문에 인용한 출처를 클릭할 수 있는 링크로 눈에 잘 띄게 표시해야 합니다.

12345678910111213141516171819202122[
  {
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "the model response is here...",
      "refusal": null,
      "annotations": [
        {
          "type": "url_citation",
          "url_citation": {
            "end_index": 985,
            "start_index": 764,
            "title": "Page title...",
            "url": "https://..."
          }
        }
      ]
    },
    "finish_reason": "stop"
  }
]

기존 웹 검색에서 마이그레이션하기

현재 사용 중인 도구 또는 모델	권장 방식	참고 사항
Responses의 `web_search_preview`	`web_search`로 마이그레이션	`web_search`는 `filters`, `external_web_access`, `return_token_budget` 같은 최신 설정을 지원합니다.
`gpt-4o-search-preview` 또는 `gpt-4o-mini-search-preview`	Responses의 `web_search`로 마이그레이션하거나, Chat Completions를 유지해야 한다면 `gpt-5-search-api` 사용	프리뷰 검색 모델은 사용 중단 예정(deprecated)으로 지정된 후 2026년 7월 23일에 종료되었습니다.
Chat Completions 검색 통합	`gpt-5-search-api`를 사용하거나, 더 다양한 도구 설정과 선택적 검색이 필요하면 Responses의 `web_search`로 마이그레이션	Chat Completions 검색 모델은 응답 전에 항상 검색합니다. Responses에서는 검색을 도구로 호출합니다.
Responses의 `o4-mini`	현재 지원되는 추론 모델로 마이그레이션하고 `web_search` 사용	이 모델은 2026년 10월 23일에 종료되었습니다.

기존 통합에서 gpt-5를 계속 사용하는 경우 웹 검색을 사용하려면 추론 수준을 minimal보다 높게 설정해야 합니다.

검색 컨텍스트 크기

search_context_size는 모델이 응답을 생성하기 전에 웹 검색 결과에서 얼마나 많은 정보를 컨텍스트로 제공할지 결정합니다. 몇 가지 세부 정보만 확인하면 되는 조회에는 low를 사용하세요. 균형 잡힌 기본 설정으로는 medium이 적합하며, 답변에 검색 결과의 세부 정보가 더 필요할 수 있다면 high를 사용하세요. 이 설정으로 정확한 토큰 수를 지정할 수는 없으며, 출처나 인용의 개수도 보장되지 않습니다.

검색 컨텍스트 크기 설정

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-6-astra",
  tools: [
    {
      type: "web_search",
      search_context_size: "low",
    },
  ],
  input: "What movie won best picture in 2025?",
});
console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "web_search",
            "search_context_size": "low",
        }
    ],
    input="What movie won best picture in 2025?",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfWebSearch(responses.WebSearchToolTypeWebSearch)
	tool.OfWebSearch.SearchContextSize = responses.WebSearchToolSearchContextSizeLow
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What movie won best picture in 2025?")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.WebSearchTool;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("What movie won best picture in 2025?")
        .addTool(
            WebSearchTool.builder()
                .type(WebSearchTool.Type.WEB_SEARCH)
                .searchContextSize(WebSearchTool.SearchContextSize.LOW)
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
    ResponseTool.CreateWebSearchTool(
        searchContextSize: WebSearchToolContextSize.Low
    )
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("What movie won best picture in 2025?")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16require "openai"

client = OpenAI::Client.new

response = client.responses.create(
  model: "gpt-6-astra",
  input: "What movie won best picture in 2025?",
  tools: [
    {
      type: :web_search,
      search_context_size: :low
    }
  ]
)

puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "tools": [{
            "type": "web_search",
            "search_context_size": "low"
        }],
        "input": "What movie won best picture in 2025?"
    }'

장시간 웹 리서치 실행

리서치에 비공개 기록도 사용한다면 공개 웹 검색과 MCP를 통한 비공개 기록 조회를 별도의 요청으로 실행하세요.

return_token_budget은 GPT-5 이상 추론 모델로 Responses API에서 검색할 때 도구가 반환할 수 있는 웹 검색 결과의 분량을 제어합니다. 대부분의 요청에는 기본값을 유지하세요. 많은 페이지를 살펴봐야 하는 집중적인 리서치나 평가에서 기본 반환 토큰 한도에 도달해 작업이 중단될 수 있는 경우에만 unlimited로 설정하세요.

unlimited를 사용하면 지연 시간과 비용이 늘어날 수 있으므로 필요한 경우에만 사용하세요. 여러 번 검색하는 장시간 작업에는 백그라운드 모드(background: true)를 사용하세요. 요청을 비동기적으로 계속 실행하고 나중에 최종 응답을 가져올 수 있습니다.

값	동작
`default`	웹 검색 결과에 기본 반환 토큰 한도를 적용합니다. `return_token_budget`을 생략했을 때와 동작이 같습니다.
`unlimited`	해당 웹 검색 실행에서 기본 반환 토큰 한도를 해제합니다.

이 매개변수는 Responses API의 호스팅형 web_search 도구로 GPT-5 이상 추론 모델의 웹 검색을 실행할 때만 적용됩니다. 검색 컨텍스트 윈도우는 바뀌지 않으며, 비추론 웹 검색, 기존 Search API 경로, 컨테이너 웹 검색, Chat Completions 검색 모델, web_search_preview에는 적용되지 않습니다. 지원하는 값은 default와 unlimited뿐입니다. null, 숫자, 그 밖의 문자열은 거부됩니다.

장시간 웹 검색 실행

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46import OpenAI from "openai";
import { Agent, fetch } from "undici";

// Allow long research runs without automatic request retries.
const timeout = 15 * 60 * 1000;
const dispatcher = new Agent({
  headersTimeout: timeout,
  bodyTimeout: timeout,
});
const client = new OpenAI({
  timeout,
  maxRetries: 0,
  fetch,
  fetchOptions: { dispatcher },
});

try {
  const stream = client.responses.stream({
    model: "gpt-6-astra",
    reasoning: { effort: "xhigh" },
    tools: [
      {
        type: "web_search",
        return_token_budget: "unlimited",
      },
    ],
    input: [
      "Research the economic impact of semaglutide on global healthcare systems.",
      "",
      "Do:",
      "- Include specific figures, trends, statistics, and measurable outcomes.",
      "- Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations (e.g., WHO, CDC), regulatory agencies, or pharmaceutical earnings reports.",
      "- Include inline citations and return all source metadata.",
      "",
      "Be analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling.",
    ].join("\n"),
  });

  const response = await stream.finalResponse();
  if (response.status !== "completed") {
    throw new Error(`Research response ended with status ${response.status}`);
  }
  console.log(response.output_text);
} finally {
  await dispatcher.close();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "xhigh"},
    tools=[
        {
            "type": "web_search",
            "return_token_budget": "unlimited",
        }
    ],
    input="""Research the economic impact of semaglutide on global healthcare systems.

Do:
- Include specific figures, trends, statistics, and measurable outcomes.
- Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations (e.g., WHO, CDC), regulatory agencies, or pharmaceutical earnings reports.
- Include inline citations and return all source metadata.

Be analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling.""",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37package main

import (
	"context"
	"fmt"
	"strings"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
	"github.com/openai/openai-go/v3/shared"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfWebSearch(responses.WebSearchToolTypeWebSearch)
	tool.OfWebSearch.SetExtraFields(map[string]any{"return_token_budget": "unlimited"})
	input := strings.Join([]string{
		"Research the economic impact of semaglutide on global healthcare systems.",
		"",
		"Do:",
		"- Include specific figures, trends, statistics, and measurable outcomes.",
		"- Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations, regulatory agencies, or pharmaceutical earnings reports.",
		"- Include inline citations and return all source metadata.",
		"",
		"Be analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling.",
	}, "\n")
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:     "gpt-6-astra",
		Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortXhigh},
		Tools:     []responses.ToolUnionParam{tool},
		Input:     responses.ResponseNewParamsInputUnion{OfString: openai.String(input)},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.WebSearchTool;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            "Research the economic impact of semaglutide on global healthcare systems. Include current figures and citations.")
        .reasoning(Reasoning.builder().effort(ReasoningEffort.XHIGH).build())
        .addTool(
            WebSearchTool.builder()
                .type(WebSearchTool.Type.WEB_SEARCH)
                .putAdditionalProperty("return_token_budget", JsonValue.from("unlimited"))
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  input: "Research the economic impact of semaglutide on global healthcare systems. Include current figures and citations.",
  reasoning: { effort: :xhigh },
  tools: [
    {
      type: :web_search,
      return_token_budget: :unlimited
    }
  ]
)

puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "reasoning": { "effort": "xhigh" },
    "tools": [
      {
        "type": "web_search",
        "return_token_budget": "unlimited"
      }
    ],
    "input": "Research the economic impact of semaglutide on global healthcare systems.\n\nDo:\n- Include specific figures, trends, statistics, and measurable outcomes.\n- Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations (e.g., WHO, CDC), regulatory agencies, or pharmaceutical earnings reports.\n- Include inline citations and return all source metadata.\n\nBe analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling."
  }'

도메인 필터링

도메인 필터링을 사용하면 웹 검색 결과를 특정 도메인으로 제한할 수 있습니다. filters 매개변수에서 allowed_domains에 허용할 도메인을 최대 100개 지정하거나 blocked_domains에 차단할 도메인을 최대 100개 지정할 수 있습니다. 도메인을 입력할 때는 HTTP 또는 HTTPS 접두사를 생략하세요. 예를 들어 openai.com으로 입력하세요. https://openai.com/처럼 전체 URL을 입력하지 마세요. 지정한 도메인의 하위 도메인에도 필터가 적용됩니다. 도메인 필터링은 Responses API의 web_search 도구에서만 사용할 수 있습니다.

출처

웹 검색 중에 가져온 모든 URL을 확인하려면 sources 필드를 사용하세요. 본문 인용에는 가장 관련성 높은 출처만 표시되지만, sources 필드는 모델이 응답을 작성할 때 참조한 전체 URL 목록을 반환합니다. 출처 수는 인용 수보다 많은 경우가 흔합니다. 외부 제공업체의 실시간 피드도 이 목록에 oai-sports, oai-weather 또는 oai-finance로 표시됩니다. sources 필드는 web_search와 web_search_preview 도구 모두에서 사용할 수 있습니다.

출처 목록 조회

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "low" },
  tools: [
    {
      type: "web_search",
      filters: {
        allowed_domains: [
          "pubmed.ncbi.nlm.nih.gov",
          "clinicaltrials.gov",
          "www.who.int",
          "www.cdc.gov",
          "www.fda.gov",
        ],
        blocked_domains: ["reddit.com", "quora.com", "wikipedia.org"],
      },
    },
  ],
  tool_choice: "auto",
  include: ["web_search_call.action.sources"],
  input:
    "Please perform a web search on how semaglutide is used in the treatment of diabetes.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "low"},
    tools=[
        {
            "type": "web_search",
            "filters": {
                "allowed_domains": [
                    "pubmed.ncbi.nlm.nih.gov",
                    "clinicaltrials.gov",
                    "www.who.int",
                    "www.cdc.gov",
                    "www.fda.gov",
                ],
                "blocked_domains": [
                    "reddit.com",
                    "quora.com",
                    "wikipedia.org",
                ],
            },
        }
    ],
    tool_choice="auto",
    include=["web_search_call.action.sources"],
    input="Please perform a web search on how semaglutide is used in the treatment of diabetes.",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
	"github.com/openai/openai-go/v3/shared"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfWebSearch(responses.WebSearchToolTypeWebSearch)
	tool.OfWebSearch.Filters = responses.WebSearchToolFiltersParam{
		AllowedDomains: []string{"pubmed.ncbi.nlm.nih.gov", "clinicaltrials.gov", "www.who.int", "www.cdc.gov", "www.fda.gov"},
	}
	tool.OfWebSearch.Filters.SetExtraFields(map[string]any{"blocked_domains": []string{"reddit.com", "quora.com", "wikipedia.org"}})
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:     "gpt-6-astra",
		Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortLow},
		Tools:     []responses.ToolUnionParam{tool},
		Include:   []responses.ResponseIncludable{responses.ResponseIncludableWebSearchCallActionSources},
		Input:     responses.ResponseNewParamsInputUnion{OfString: openai.String("Please perform a web search on how semaglutide is used in the treatment of diabetes.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseIncludable;
import com.openai.models.responses.WebSearchTool;
import java.util.List;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("Search for how semaglutide is used in the treatment of diabetes.")
        .reasoning(Reasoning.builder().effort(ReasoningEffort.LOW).build())
        .addInclude(ResponseIncludable.of("web_search_call.action.sources"))
        .addTool(
            WebSearchTool.builder()
                .type(WebSearchTool.Type.WEB_SEARCH)
                .filters(
                    WebSearchTool.Filters.builder()
                        .allowedDomains(
                            List.of(
                                "pubmed.ncbi.nlm.nih.gov",
                                "clinicaltrials.gov",
                                "www.who.int",
                                "www.cdc.gov",
                                "www.fda.gov"))
                        .putAdditionalProperty(
                            "blocked_domains",
                            JsonValue.from(List.of("reddit.com", "quora.com", "wikipedia.org")))
                        .build())
                .build())
        .build();

var response = client.responses().create(params);
response.output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));
response.output().stream()
    .flatMap(item -> item.webSearchCall().stream())
    .flatMap(call -> call.action().search().stream())
    .flatMap(action -> action.sources().stream())
    .flatMap(List::stream)
    .forEach(source -> System.out.println(source.url()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37require "openai"

client = OpenAI::Client.new

response = client.responses.create(
  model: "gpt-6-astra",
  reasoning: { effort: :low },
  input: "Search for how semaglutide is used in the treatment of diabetes.",
  include: ["web_search_call.action.sources"],
  tools: [
    {
      type: :web_search,
      filters: {
        allowed_domains: [
          "pubmed.ncbi.nlm.nih.gov",
          "clinicaltrials.gov",
          "www.who.int",
          "www.cdc.gov",
          "www.fda.gov"
        ],
        blocked_domains: ["reddit.com", "quora.com", "wikipedia.org"]
      }
    }
  ]
)

puts(response.output_text)
response.output
        .grep(OpenAI::Models::Responses::ResponseFunctionWebSearch)
        .each do |search_call|
          action = search_call.action
          next unless action.is_a?(
            OpenAI::Models::Responses::ResponseFunctionWebSearch::Action::Search
          )

          Array(action.sources).each { |source| puts(source.url) }
        end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "reasoning": { "effort": "low" },
    "tools": [
      {
        "type": "web_search",
        "filters": {
          "allowed_domains": [
            "pubmed.ncbi.nlm.nih.gov",
            "clinicaltrials.gov",
            "www.who.int",
            "www.cdc.gov",
            "www.fda.gov"
          ],
          "blocked_domains": [
            "reddit.com",
            "quora.com",
            "wikipedia.org"
          ]
        }
      }
    ],
    "tool_choice": "auto",
    "include": ["web_search_call.action.sources"],
    "input": "Please perform a web search on how semaglutide is used in the treatment of diabetes."
  }'

이미지 검색 결과

웹 검색은 일반 텍스트 결과와 함께 이미지 결과를 반환할 수 있습니다. 애플리케이션에 제품 사진, 랜드마크, 장소, 행사, 참고 이미지 등 최신 시각 자료나 웹에서 찾은 시각 자료가 필요할 때 이미지 검색을 사용하세요.

이미지 검색을 사용하려면 search_content_types에 image를 포함하세요. 모델이 검색한 이미지를 요약하거나 순위를 매기거나 설명하는 데 도움이 되는 텍스트 결과도 필요하다면 text를 추가하세요.

image_settings에서 이미지 검색에만 적용되는 동작을 설정할 수 있습니다.

max_results: 요청할 이미지 결과 수를 양의 정수로 지정하세요.
caption: 짧은 이미지 설명이 있으면 함께 반환하도록 요청하세요.

원본 이미지 결과를 확인하려면 요청에 web_search_call.results를 포함하고 응답에서 web_search_call.results[]를 읽으세요. 이미지 결과는 어시스턴트 메시지와 별도로 반환되므로 애플리케이션에서 URL이나 메타데이터가 필요할 때는 web_search_call 항목을 직접 파싱하세요.

이미지 검색

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "low" },
  tools: [
    {
      type: "web_search",
      search_content_types: ["image", "text"],
      image_settings: {
        max_results: 3,
        caption: true,
      },
    },
  ],
  include: ["web_search_call.results"],
  input:
    "Search for recent images and supporting text sources about the Golden Gate Bridge at sunset.",
});

console.log(response.output);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "low"},
    tools=[
        {
            "type": "web_search",
            "search_content_types": ["image", "text"],
            "image_settings": {
                "max_results": 3,
                "caption": True,
            },
        }
    ],
    include=["web_search_call.results"],
    input="Search for recent images and supporting text sources about the Golden Gate Bridge at sunset.",
)

print(response.output)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
	"github.com/openai/openai-go/v3/shared"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfWebSearch(responses.WebSearchToolTypeWebSearch)
	tool.OfWebSearch.SetExtraFields(map[string]any{
		"search_content_types": []string{"image", "text"},
		"image_settings":       map[string]any{"max_results": 3, "caption": true},
	})
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model:     "gpt-6-astra",
		Reasoning: shared.ReasoningParam{Effort: shared.ReasoningEffortLow},
		Tools:     []responses.ToolUnionParam{tool},
		Include:   []responses.ResponseIncludable{responses.ResponseIncludableWebSearchCallResults},
		Input:     responses.ResponseNewParamsInputUnion{OfString: openai.String("Search for recent images and supporting text sources about the Golden Gate Bridge at sunset.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.Output)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.Reasoning;
import com.openai.models.ReasoningEffort;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.ResponseIncludable;
import com.openai.models.responses.WebSearchTool;
import java.util.List;
import java.util.Map;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            "Search for recent images and supporting text sources about the Golden Gate Bridge at sunset.")
        .reasoning(Reasoning.builder().effort(ReasoningEffort.LOW).build())
        .addInclude(ResponseIncludable.of("web_search_call.results"))
        .addTool(
            WebSearchTool.builder()
                .type(WebSearchTool.Type.WEB_SEARCH)
                .putAdditionalProperty(
                    "search_content_types", JsonValue.from(List.of("image", "text")))
                .putAdditionalProperty(
                    "image_settings", JsonValue.from(Map.of("max_results", 3, "caption", true)))
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.webSearchCall().stream())
    .map(call -> call._additionalProperties().get("results"))
    .filter(java.util.Objects::nonNull)
    .forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22require "openai"

client = OpenAI::Client.new

response = client.responses.create(
  model: "gpt-6-astra",
  reasoning: { effort: :low },
  input: "Search for recent images and supporting text sources about the Golden Gate Bridge at sunset.",
  include: ["web_search_call.results"],
  tools: [
    {
      type: :web_search,
      search_content_types: ["image", "text"],
      image_settings: {
        max_results: 3,
        caption: true
      }
    }
  ]
)

puts(response.output)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "reasoning": { "effort": "low" },
    "tools": [
      {
        "type": "web_search",
        "search_content_types": ["image", "text"],
        "image_settings": {
          "max_results": 3,
          "caption": true
        }
      }
    ],
    "include": ["web_search_call.results"],
    "input": "Search for recent images and supporting text sources about the Golden Gate Bridge at sunset."
  }'

각 image_result에는 다음이 포함됩니다.

image_url: 검색 결과 이미지의 정규 URL입니다.
source_website_url: 이미지를 찾은 페이지의 URL입니다.
thumbnail_url: 썸네일이 있으면 해당 URL을 제공합니다.
caption: 짧은 캡션이나 설명이 있으면 제공합니다.

1234567891011121314151617{
  "output": [
    {
      "type": "web_search_call",
      "status": "completed",
      "results": [
        {
          "type": "image_result",
          "image_url": "https://cdn.example/golden-gate-sunset.jpg",
          "thumbnail_url": "https://cdn.example/golden-gate-sunset-thumb.jpg",
          "source_website_url": "https://example.com/source-page",
          "caption": "Golden Gate Bridge at sunset"
        }
      ]
    }
  ]
}

사용자 위치

지역에 맞는 검색 결과를 얻으려면 국가, 도시, 지역, 시간대 중 하나 이상을 사용해 사용자의 대략적인 위치를 지정하세요.

city와 region 필드에는 자유 형식의 문자열을 입력합니다. 예를 들어 각각 Minneapolis와 Minnesota를 지정할 수 있습니다.
country 필드에는 두 글자로 된 ISO 국가 코드를 입력합니다. 예를 들면 US입니다.
timezone 필드에는 IANA 시간대를 입력합니다. 예를 들면 America/Chicago입니다.

사용자 위치 설정

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-6-astra",
  tools: [
    {
      type: "web_search",
      user_location: {
        type: "approximate",
        country: "GB",
        city: "London",
        region: "London",
      },
    },
  ],
  input: "What are the best restaurants near me?",
});
console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "web_search",
            "user_location": {
                "type": "approximate",
                "country": "GB",
                "city": "London",
                "region": "London",
            },
        }
    ],
    input="What are the best restaurants near me?",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfWebSearch(responses.WebSearchToolTypeWebSearch)
	tool.OfWebSearch.UserLocation = responses.WebSearchToolUserLocationParam{
		Type:    "approximate",
		Country: openai.String("GB"),
		City:    openai.String("London"),
		Region:  openai.String("London"),
	}
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What are the best restaurants near me?")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.WebSearchTool;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("What are the best restaurants near me?")
        .addTool(
            WebSearchTool.builder()
                .type(WebSearchTool.Type.WEB_SEARCH)
                .userLocation(
                    WebSearchTool.UserLocation.builder()
                        .type(WebSearchTool.UserLocation.Type.APPROXIMATE)
                        .city("London")
                        .country("GB")
                        .region("London")
                        .build())
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23using OpenAI.Responses;
#pragma warning disable OPENAI001

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
ResponsesClient client = new(key);

CreateResponseOptions options = new() { Model = "gpt-6-astra" };
options.Tools.Add(
    ResponseTool.CreateWebSearchTool(
        userLocation: WebSearchToolLocation.CreateApproximateLocation(
            country: "GB",
            city: "London",
            region: "London"
        )
    )
);
options.InputItems.Add(
    ResponseItem.CreateUserMessageItem("What are the best restaurants near me?")
);

ResponseResult response = await client.CreateResponseAsync(options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21require "openai"

client = OpenAI::Client.new

response = client.responses.create(
  model: "gpt-6-astra",
  input: "What are the best restaurants near me?",
  tools: [
    {
      type: :web_search,
      user_location: {
        type: :approximate,
        country: "GB",
        city: "London",
        region: "London"
      }
    }
  ]
)

puts(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-6-astra",
        "tools": [{
            "type": "web_search",
            "user_location": {
                "type": "approximate",
                "country": "GB",
                "city": "London",
                "region": "London"
            }
        }],
        "input": "What are the best restaurants near me?"
    }'

사용자 위치 설정

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import OpenAI from "openai";
const client = new OpenAI();

const completion = await client.chat.completions.create({
  model: "gpt-5-search-api",
  web_search_options: {
    user_location: {
      type: "approximate",
      approximate: {
        country: "GB",
        city: "London",
        region: "London",
      },
    },
  },
  messages: [
    {
      role: "user",
      content: "What are the best restaurants near me?",
    },
  ],
});
console.log(completion.choices[0].message.content);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5-search-api",
    web_search_options={
        "user_location": {
            "type": "approximate",
            "approximate": {
                "country": "GB",
                "city": "London",
                "region": "London",
            },
        },
    },
    messages=[
        {
            "role": "user",
            "content": "What are the best restaurants near me?",
        }
    ],
)

print(completion.choices[0].message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	completion, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: "gpt-5-search-api",
		WebSearchOptions: openai.ChatCompletionNewParamsWebSearchOptions{
			UserLocation: openai.ChatCompletionNewParamsWebSearchOptionsUserLocation{
				Approximate: openai.ChatCompletionNewParamsWebSearchOptionsUserLocationApproximate{
					Country: openai.String("GB"),
					City:    openai.String("London"),
					Region:  openai.String("London"),
				},
			},
		},
		Messages: []openai.ChatCompletionMessageParamUnion{openai.UserMessage("What are the best restaurants near me?")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(completion.Choices[0].Message.Content)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

ChatCompletionCreateParams params =
    ChatCompletionCreateParams.builder()
        .model("gpt-5-search-api")
        .addUserMessage("What are the best restaurants near me?")
        .webSearchOptions(
            ChatCompletionCreateParams.WebSearchOptions.builder()
                .userLocation(
                    ChatCompletionCreateParams.WebSearchOptions.UserLocation.builder()
                        .approximate(
                            ChatCompletionCreateParams.WebSearchOptions.UserLocation.Approximate
                                .builder()
                                .country("GB")
                                .city("London")
                                .region("London")
                                .build())
                        .build())
                .build())
        .build();

client.chat().completions().create(params).choices().stream()
    .flatMap(choice -> choice.message().content().stream())
    .forEach(System.out::println);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"

client = OpenAI::Client.new
completion = client.chat.completions.create(
  model: "gpt-5-search-api",
  messages: [
    {
      role: :user,
      content: "What are the best restaurants near me?"
    }
  ],
  web_search_options: {
    user_location: {
      type: :approximate,
      approximate: {
        country: "GB",
        city: "London",
        region: "London"
      }
    }
  }
)

puts(completion.choices.fetch(0).message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20curl -X POST "https://api.openai.com/v1/chat/completions" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-type: application/json" \
    -d '{
        "model": "gpt-5-search-api",
        "web_search_options": {
            "user_location": {
                "type": "approximate",
                "approximate": {
                    "country": "GB",
                    "city": "London",
                    "region": "London"
                }
            }
        },
        "messages": [{
            "role": "user",
            "content": "What are the best restaurants near me?"
        }]
    }'

실시간 인터넷 접근

Responses API에서는 웹 검색 도구가 실시간 콘텐츠를 가져올지, 캐시 또는 색인에 있는 결과만 사용할지 설정할 수 있습니다.

external_web_access: false를 web_search 도구에 설정하면 오프라인 모드로 실행되어 캐시된 결과만 사용합니다.
설정을 생략하면 기본값은 true이며 실시간 접근이 허용됩니다.
프리뷰 베리언트(web_search_preview)는 이 매개변수를 무시하고 external_web_access가 true인 것처럼 동작합니다.

실시간 인터넷 접근 제어

curl

1
2
3
4
5
6
7
8
9
10
11curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [
      { "type": "web_search", "external_web_access": false }
    ],
    "tool_choice": "auto",
    "input": "Find when the Eiffel Tower opened to the public and cite the source."
  }'

1
2
3
4
5
6
7
8
9
10
11import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  tools: [{ type: "web_search", external_web_access: false }],
  tool_choice: "auto",
  input: "Find when the Eiffel Tower opened to the public and cite the source.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-6-astra",
    tools=[{"type": "web_search", "external_web_access": False}],
    tool_choice="auto",
    input="Find when the Eiffel Tower opened to the public and cite the source.",
)
print(resp.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolParamOfWebSearch(responses.WebSearchToolTypeWebSearch)
	tool.OfWebSearch.SetExtraFields(map[string]any{"external_web_access": false})
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Find when the Eiffel Tower opened to the public and cite the source.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.models.responses.WebSearchTool;

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("Find when the Eiffel Tower opened to the public and cite the source.")
        .addTool(
            WebSearchTool.builder()
                .type(WebSearchTool.Type.WEB_SEARCH)
                .putAdditionalProperty("external_web_access", JsonValue.from(false))
                .build())
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16require "openai"

client = OpenAI::Client.new

response = client.responses.create(
  model: "gpt-6-astra",
  input: "Find when the Eiffel Tower opened to the public and cite the source.",
  tools: [
    {
      type: :web_search,
      external_web_access: false
    }
  ]
)

puts(response.output_text)

제한 사항

Chat Completions API

Chat Completions API에서는 검색 전용 모델만 웹 검색을 지원합니다. 이 모델들은 도메인 필터, 전체 출처 목록, 실시간 접근 제어, 반환 토큰 한도 설정 등 Responses API의 web_search 기능을 지원하지 않습니다.

모델	컨텍스트 윈도우	제한 사항
`gpt-5-search-api`	200k	Chat Completions 검색 모델 경로를 사용합니다.

Responses API

호스팅형 web_search 도구를 사용하세요. Responses API는 기존 통합을 위해 web_search_preview를 계속 지원하지만 새로 통합할 때는 web_search를 사용하세요.

사용하는 모델의 컨텍스트 윈도우가 더 크더라도 웹 검색 컨텍스트 윈도우는 128k로 제한됩니다. gpt-6-astra 또는 다른 지원 모델의 컨텍스트 한도는 해당 모델 페이지에서 확인하세요.

gpt-5.4의 추론 수준을 none으로 설정하면 결과 품질이 낮아질 수 있습니다.
Responses API 웹 검색에는 사용하는 모델의 등급별 요청 한도가 적용됩니다.
web_search_preview는 filters와 return_token_budget을 지원하지 않으며 external_web_access를 무시합니다.
tool_choice: "auto"로 설정하면 검색 여부는 모델이 결정합니다. 검색을 반드시 실행해야 한다면 tool_choice: "required"를 사용하거나 특정 웹 검색 도구를 지정하세요.

사용 시 참고 사항

API 지원 여부	요청 한도	참고 사항
Responses Chat Completions Assistants	도구와 함께 사용하는 모델의 등급별 요청 한도와 같습니다.	요금 ZDR 및 데이터 레지던시

추천

시작하기

핵심 개념

SDK 및 CLI

클라우드 제공업체

자료

레거시 API

모델 선택하기

텍스트 및 코드

프롬프트 작성

추론

이미지

실시간 처리 및 오디오

특화 모델

Agents API

Agents SDK

ChatKit

검색 및 정보 조회

도구와 데이터 연결하기

도구를 활용한 워크플로우 구축하기

컴퓨터 및 코드

미디어

GPT-Live

Realtime API

음성 기능 개발

연결

오디오 처리

서비스 출시하기

성능 및 품질

평가

비용 및 처리량

안전 및 거버넌스

인프라 및 접근 권한

운영

핵심 개념

기획

개발

테스트 및 게시

전환 명세

가이드

자료

사용자 식별

ChatGPT 요금제 사용량

가이드

파일 업로드

API

성과 측정

광고주 API

API 레퍼런스

시작하기

시작하기

기초

둘러보기

지원 플랫폼

릴리스

워크플로우

주요 기능

Sites

dot

ChatGPT 스페이스

레퍼런스

맞춤 설정

설정 파일

에이전트 설정

ChatGPT와 Codex 확장하기

Linux

Windows

개발 워크플로우

확장 및 자동화

환경

Codex Cloud

Codex로 개발하기

서드 파티 통합

레퍼런스

권한

Codex Security

사이버 안전

시작하기

기능 설정

ID 및 액세스