How to Add Real-Time Web Search to Your AI App (HeFu web-search API, $0.007/Search)
How to add real-time web search to your AI app with one API call: HeFu's web-search model, POST /v1/search, per-search pricing at $0.007, and source citations.
HeFu · Published 2026-11-127 min read
Retrieval-augmented AI apps live or die on freshness: a coding assistant that quotes last year's pricing, or a support bot that misses this morning's outage announcement, loses user trust fast. According to OpenAI's cookbook guidance on retrieval (2024–2026 updates), the standard fix is to search first, then synthesize — but standing up your own search stack (crawler, index, ranking, snippet extraction) is weeks of work. A hosted search API collapses that to one HTTP call. This guide shows how to add real-time web search to an AI app using HeFu's web-search model: the request format, the response shape, per-search pricing, and three integration patterns that work in production.
What the web-search API Is
web-search is a search model in the HeFu model catalog (listed under the 联网搜索 / web-search category, as of November 2026). Instead of generating text, it takes a query, searches the live web, and returns a structured list of results — title, URL, and snippet — that you can feed into any downstream model. It runs on the same OpenAI-compatible platform as the chat models: one API key at https://api.hefu.hk/v1, one balance, one bill.
Pricing is per successful search: $0.007 per search as of November 2026 (per the public search pricing page; prices can change, so check the live page before budgeting). Empty result sets are not charged, so exploratory queries that find nothing cost nothing. This is dramatically simpler than token-based billing for search: you know exactly what a search costs, and you can show your users a per-search price without a spreadsheet.
Your First Search: The Request and Response
The endpoint is POST /v1/search (not /v1/chat/completions — search has its own route). The minimal request body has three fields:
curl -X POST https://api.hefu.hk/v1/search \
-H "Authorization: Bearer $HEFU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "web-search",
"query": "latest AI news",
"max_results": 5,
"enrich": false
}'
model— alwaysweb-search.query— the natural-language search string; no query syntax to learn.max_results— how many results to return (5 is a good default for RAG; raise it for broad research tasks).enrich— set per the API documentation at hefu.hk/docs when you need expanded content for specific pipelines.
The response is a search.results object. In our November 2026 test, the query "latest AI news" returned provider: "specstream" and five results including Reuters' AI section and the USPTO AI reports page, each with title, url, and a snippet long enough to judge relevance. The payload shape is intentionally boring — no nested embeddings, no ranking metadata to decode — so piping it into an LLM prompt takes about five lines of code:
import os, requests
def search_web(query: str, max_results: int = 5) -> list[dict]:
r = requests.post(
"https://api.hefu.hk/v1/search",
headers={"Authorization": f"Bearer {os.environ['HEFU_API_KEY']}"},
json={"model": "web-search", "query": query,
"max_results": max_results, "enrich": False},
timeout=30,
)
r.raise_for_status()
return r.json()["results"]
def answer_with_sources(question: str, model: str = "deepseek-v4-flash") -> str:
results = search_web(question)
context = "\n\n".join(f"[{i+1}] {r['title']} — {r['snippet']} ({r['url']})"
for i, r in enumerate(results))
resp = requests.post(
"https://api.hefu.hk/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['HEFU_API_KEY']}"},
json={"model": model,
"messages": [
{"role": "system", "content":
"Answer using the sources below. Cite with [n]. "
"Say when the sources do not cover the question."},
{"role": "user", "content": f"Sources:\n{context}\n\nQuestion: {question}"},
]},
timeout=60,
)
resp.raise_for_status()
return resp.json()["choices"][0]["message"]["content"]
Three Integration Patterns That Hold Up in Production
1. Search-Then-Answer (RAG over the live web)
The pattern above — search, inject snippets, synthesize with citations — is the workhorse for assistants, research tools, and support bots. Two production details matter. First, cap max_results at 5–8: beyond that, snippet noise degrades answer quality faster than extra coverage helps (a finding consistently reported in RAG evaluation practice, Anthropic, 2024). Second, always show sources in the UI; users trust cited answers measurably more, and source links are your cheapest defense against hallucination complaints.
2. Per-Request Freshness Checks for Agents
Tool-calling agents can route specific sub-questions to web-search as a tool while handling reasoning with a flagship model. Register the tool with a plain-JSON schema (query, optional max_results), and have the agent call it whenever the user asks about anything time-sensitive — news, prices, versions, "is X down right now". Because billing is per search and empty results are free, you can afford a freshness check on every suspicious question; at $0.007, even 1,000 freshness checks a day cost $7.
3. Human-in-the-Loop Research Digests
Content and growth teams use web-search to pull source lists for briefs: query the topic, get titled, URL'd, snippeted results, and hand the list to a writer or to a chat model for synthesis. The workbench for the web-search model (in the model catalog under 联网搜索, as of November 2026) lets you run these queries interactively and inspect sources before committing code — a fast way to sanity-check result quality for your target queries.
Cost Model: What Search Adds to Your Bill
At $0.007 per search (November 2026, per the live pricing page), a search-then-answer turn costs the search fee plus the chat tokens. A realistic breakdown for one answered question: one search ($0.007) + ~2K tokens of snippets and prompt on a mid-tier model (cents at most on HeFu's pay-as-you-go rates) + a few hundred output tokens. For most apps the search fee is the dominant per-turn cost only until you move to expensive flagship models — after which token spend overtakes it. If you cache identical queries for 15 seconds at the gateway layer (HeFu applies a short cache for repeated identical search calls), popular repeated questions stop costing anything at all during the cache window.
Limits and Honest Caveats
Search results reflect the public web: coverage varies by language and region, and snippets are excerpts, not full text — for deep reading, fetch the source page. Provider routing (SpecStream primary with a DuckDuckGo fallback, as of November 2026) is a platform detail that can change; do not hard-code the provider value into business logic. And as with every model on the platform, your end users must respect each source site's terms — search results are for ingestion and citation, not wholesale republication.
FAQ
How much does the HeFu web-search API cost?
Web search is billed per successful search at $0.007 (as of November 2026, per the public search pricing page at hefu.hk/public/search-pricing). Empty result sets are not charged. There is no monthly commitment — it settles against the same API balance as your model calls.
What endpoint do I call to search the web through HeFu?
Send a POST request to https://api.hefu.hk/v1/search with your HeFu API key and a JSON body like {"model":"web-search","query":"latest AI news","max_results":5,"enrich":false}. The response is a search.results object with a provider field and a results array of title, URL, and snippet — ready to inject into an LLM prompt or render in your UI.
Does the web-search API return sources I can cite?
Yes. Each result includes the page title, URL, and a text snippet from the source, so your app can link back to origins and show citations. In our November 2026 test with the query "latest AI news", the API returned results from major outlets including Reuters and the USPTO AI initiative page, each with a usable snippet.
Can I use web search together with chat models in one integration?
Yes. Web search uses the same base URL and API key as every other model on the platform, so you can run a web-search call first, append the snippets to your system prompt, and then call POST /v1/chat/completions with GPT-5.6, Claude Opus 5, DeepSeek-V4, Kimi K3 or any model in the catalog — one balance, one key.
Get Building
If your app needs to know what happened today, not last year, create a key in the HeFu console and run your first search — then pick a chat model from the live catalog to turn results into answers. For multi-provider routing patterns that pair well with search, see How to Build an AI App with Multiple LLM Providers and How Can a Startup Reduce LLM API Costs.
FAQ
How much does the HeFu web-search API cost?
Web search is billed per successful search at $0.007 (as of November 2026, per the public search pricing page at [hefu.hk/public/search-pricing](https://hefu.hk/public/search-pricing)). Empty result sets are not charged. There is no monthly commitment — it settles against the same API balance as your model calls.
What endpoint do I call to search the web through HeFu?
Send a POST request to `https://api.hefu.hk/v1/search` with your HeFu API key and a JSON body like `{"model":"web-search","query":"latest AI news","max_results":5,"enrich":false}`. The response is a `search.results` object with a `provider` field and a `results` array of title, URL, and snippet — ready to inject into an LLM prompt or render in your UI.
Does the web-search API return sources I can cite?
Yes. Each result includes the page title, URL, and a text snippet from the source, so your app can link back to origins and show citations. In our November 2026 test with the query "latest AI news", the API returned results from major outlets including Reuters and the USPTO AI initiative page, each with a usable snippet.
Can I use web search together with chat models in one integration?
Yes. Web search uses the same base URL and API key as every other model on the platform, so you can run a `web-search` call first, append the snippets to your system prompt, and then call `POST /v1/chat/completions` with GPT-5.6, Claude Opus 5, DeepSeek-V4, Kimi K3 or any model in the catalog — one balance, one key.