# AI 지향 실시간 웹 검색. **API:** Data API **Endpoint:** `POST /v1/beta/byteplus/web-search` **Tags:** BytePlus AI 에이전트용으로 구축된 실시간 웹 검색을 실행하고 링크와 스니펫이 포함된 제목 있는 결과의 순위 목록을 반환합니다. `Query`는 필수이며, `Count`(≤ 20), `Filter`(`Sites`로 제한하거나 `BlockHosts` 제외), `Language`, `TimeRange`로 결과 집합을 좁힐 수 있습니다. 응답은 `ResponseMetadata.RequestId`와 웹 결과의 `Result` 목록을 감쌉니다. RAG 검색 증강, 경쟁사/PR 모니터링, 팩트 체크, 콘텐츠 소싱에 사용하며, 각 결과 URL을 `post_byteplus_fetch`와 함께 사용해 전체 페이지 콘텐츠를 가져오세요. ### 가격 참고 - 과금 방식: 성공한 요청당 고정 원가 기준. - 참조 요청 추정치: USD 0.0048. - 참조 고객 배수: 1.0. 정산된 고객 금액에 다시 적용하지 마세요. 참조 메타데이터일 뿐이며 계정 견적이나 보장된 가격 또는 지출 한도가 아닙니다. 리소스 크레딧은 Felo 크레딧이 아닙니다. 최종 청구는 Felo 청구 기록을 따릅니다. ## Base URL - `https://openapi.felo.ai` ## Authentication - `FeloBearerAuth` (http bearer, bearer format Felo API Key) - `FeloApiKey` (apiKey in header `X-API-Key`) ## Request body Required: **yes** ### application/json Schema: ```json { "type": "object", "properties": { "Query": { "type": "string", "description": "검색 쿼리입니다. 필수입니다. 최대 400자이며, 업스트림 엔진도 실질적으로 약 50단어에서 제한됩니다.", "example": "OpenAI news", "maxLength": 400 }, "Count": { "type": "integer", "description": "반환할 결과 수입니다. 선택 사항이며 기본값은 10, 최댓값은 20입니다.", "maximum": 20, "example": 10, "default": 10 }, "Filter": { "type": "object", "description": "선택적 결과 필터입니다. 두 필드 모두 전체 도메인을 파이프로 구분한 문자열입니다(각 최대 5개).", "properties": { "Sites": { "type": "string", "description": "결과를 이 전체 도메인으로 제한합니다. 파이프로 구분하며 최대 5개입니다(예: \"bytedance.com|byteplus.com\"). 배열을 전송하면 10400 Invalid Parameter가 반환됩니다.", "example": "bytedance.com|byteplus.com" }, "BlockHosts": { "type": "string", "description": "이 전체 도메인의 결과를 제외합니다. 파이프로 구분하며 최대 5개입니다(예: \"reddit.com|quora.com\").", "example": "reddit.com|quora.com" } } }, "Language": { "type": "string", "description": "업스트림 형식의 선택적 언어 힌트입니다(예: EN, ZH-HANS, ZH-HANT).", "example": "EN" }, "TimeRange": { "description": "선택적 최신성 기간입니다. 지정된 기간인 OneDay / OneWeek / OneMonth / OneYear 중 하나이거나 사용자 지정 범위 \"YYYY-MM-DD..YYYY-MM-DD\"입니다. 시간 필터를 사용하지 않으려면 생략하세요. 참고: \"week\"/\"month\" 같은 값은 업스트림에서 조용히 무시됩니다.", "oneOf": [ { "type": "string", "enum": [ "OneDay", "OneWeek", "OneMonth", "OneYear" ] }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}\\.\\.\\d{4}-\\d{2}-\\d{2}$", "description": "사용자 지정 범위입니다(예: 2026-08-01..2026-09-01)." } ], "example": "OneWeek" } }, "required": [ "Query" ] } ``` Example: ```json { "Query": "OpenAI news" } ``` ## Responses ### 200 — 검색에 성공했습니다. `Result`에 순위가 매겨진 웹 결과가 들어 있습니다. Headers: - `X-Request-Id` (string) — Felo 지원팀에 문의할 때 포함할 요청 식별자입니다. **application/json** Schema: object ```json { "type": "object", "properties": { "ResponseMetadata": { "type": "object", "description": "업스트림 요청 메타데이터입니다.", "properties": { "RequestId": { "type": "string", "description": "이 요청의 고유 식별자입니다." }, "Action": { "type": "string" }, "Version": { "type": "string" }, "Service": { "type": "string" }, "Region": { "type": "string" } } }, "Result": { "type": "object", "description": "검색 결과 페이로드입니다.", "properties": { "ResultCount": { "type": "integer", "description": "반환된 웹 결과 수입니다." }, "WebResults": { "type": "array", "description": "순위가 매겨진 웹 결과 목록입니다.", "items": { "type": "object", "properties": { "Id": { "type": "string", "description": "불투명한 결과 id입니다." }, "SortId": { "type": "integer", "description": "결과의 순위입니다(1부터 시작)." }, "Title": { "type": "string", "description": "결과 제목입니다." }, "SiteName": { "type": "string", "description": "출처 사이트 이름입니다(비어 있을 수 있음)." }, "Url": { "type": "string", "description": "결과 URL입니다." }, "Snippet": { "type": "string", "description": "페이지에서 발췌한 짧은 텍스트 스니펫입니다." }, "Summary": { "type": "string", "description": "페이지 콘텐츠의 긴 요약입니다." }, "PublishTime": { "type": "string", "description": "ISO 8601 형식의 게시 시간입니다(비어 있을 수 있음)." }, "PublishTimeUnix": { "type": "integer", "description": "게시 시간입니다(Unix 초, 알 수 없으면 0)." }, "LogoUrl": { "type": "string", "description": "서명된 사이트 로고 URL입니다(시간 제한 있음)." } } } }, "SearchContext": { "type": "object", "description": "확정된 쿼리 컨텍스트를 그대로 반환한 값입니다.", "properties": { "OriginQuery": { "type": "string" }, "SearchType": { "type": "string" } } }, "TimeCost": { "type": "integer", "description": "업스트림 처리 시간입니다(밀리초)." }, "LogId": { "type": "string", "description": "업스트림 로그 id입니다(ResponseMetadata.RequestId와 동일)." }, "Choices": { "type": [ "array", "null" ], "description": "예약됨. 해당하는 경우가 아니면 null입니다.", "items": { "type": "object" } }, "Usage": { "type": [ "object", "null" ], "description": "예약됨. 해당하는 경우가 아니면 null입니다." } } } } } ``` Example: ```json { "ResponseMetadata": { "RequestId": "20260904155503A787EC832774768DC56F", "Action": "", "Version": "", "Service": "", "Region": "" }, "Result": { "ResultCount": 3, "WebResults": [ { "Id": "19b903d59c017bbb04c7832574500d49", "SortId": 1, "Title": "OpenAI News | OpenAI", "SiteName": "OpenAI", "Url": "https://openai.com/news/", "Snippet": "Stay up to speed on the rapid advancement of AI technology and the benefits it offers to humanity.", "Summary": "Stay up to speed on the rapid advancement of AI technology and the benefits it offers to humanity.", "PublishTime": "2026-09-03T07:50:20+08:00", "PublishTimeUnix": 1788393020, "LogoUrl": "https://p16-bpsearch-sign.ibyteimg.com/..." } ], "SearchContext": { "OriginQuery": "OpenAI latest news", "SearchType": "web" }, "TimeCost": 935, "LogId": "20260904155503A787EC832774768DC56F", "Choices": null, "Usage": null } } ``` ### 400 — 요청을 처리할 수 없습니다. 요청 매개변수를 확인하세요. ### 401 — 유효한 Felo API 키가 필요합니다. ### 402 — 청구 요건이 충족되지 않아 요청을 진행할 수 없습니다. ### 403 — 이 계정에는 이 작업을 수행할 권한이 없습니다. ### 429 — 요청 또는 지출 한도에 도달했습니다. ### 502 — 서비스가 요청을 완료할 수 없습니다. ### 503 — API 또는 청구 서비스를 일시적으로 사용할 수 없습니다. ### 504 — 요청을 처리하는 동안 서비스 시간이 초과되었습니다. ### default — 오류 응답. 업스트림 패스스루 응답은 공급자 형식을 사용할 수 있습니다. **application/json** Schema: ```json {} ```