快速入门
获取密钥，复制该行，运行它，读取 JSON。
0。获取密钥
创建免费账户，打开 API 密钥 并创建一个。然后将其保存在环境变量中：
export FNA_KEY=fna_live_...1。搜索
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?q=climate+summit&size=2"{
"took_ms": 41,
"total": 1284,
"total_is_lower_bound": false,
"size": 2,
"offset": 0,
"results": [
{
"id": "9c1f8a4b2d3e5f6071829304a5b6c7d8",
"url": "https://example-news.com/world/climate-summit-opens",
"title": "Climate summit opens with a call for binding targets",
"description": "Delegates from 190 countries gathered on Monday ...",
"published_at": "2026-08-17T09:12:00Z",
"crawled_at": "2026-08-17T10:48:31Z",
"host": "example-news.com",
"sitename": "Example News",
"country": "GB",
"country_source": "cctld",
"lang": "en",
"tld": "com"
}
]
}响应中有三个字段值得立即关注。total 表示匹配的文章数量，而非返回的数量——为提升速度，该数量上限为 10,000，total_is_lower_bound 会告知你是否触达上限。country_source 说明国家是如何确定的，这很重要，因为任何新闻数据集中约有三分之一的国家值是推断得出的，而非事实。crawled_at 是真实的时间戳：发布机构可以回溯 published_at 的日期，但抓取时间由管道分配。
2。缩小范围
筛选条件在参数之间为“与”（AND）关系，在同一参数内为“或”（OR）关系。因此，country=DE,AT&lang=de 表示“来自德国或奥地利的德语文章”。以下查询要求获取来自乌克兰的乌克兰语文章，按最新优先排序：
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?country=UA&lang=uk&date=today&sort=date&size=10"3。获取全文
为保持响应体积较小，搜索结果默认不包含文章正文。在您选定真正需要的文章后，请显式请求获取正文：
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?q=inflation&full_text=true&size=5"全文长度约为每篇文章 2,000–4,000 个字符。20 篇包含 full_text=true 的文章，对于语言模型而言大约需要 40,000 个 token。请先筛选，再获取正文。详见 token 成本。
4。计数而非列出
通常，更有价值的问题不是“有哪些文章”，而是“这里是否有任何内容，以及它们在哪里”。通过极低的成本（约 200 个 token，而获取一页结果需数千个 token）统计答案数量，使其成为 AI 代理判断是否值得执行搜索时的首选调用：
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/stats?q=earthquake&date=7d"响应结果会按国家、语言、域名后缀、发布机构和日期统计数量，这些统计基于所有匹配的文章集合，而非当前页。
Python 示例
import os, requests
HEADERS = {"Authorization": "Bearer " + os.environ["FNA_KEY"]}
r = requests.get("https://freenewsapi.ai/v1/search", headers=HEADERS, params={
"q": "semiconductor export controls",
"date": "7d",
"lang": "en",
"size": 20,
"sort": "relevance",
})
for a in r.json()["results"]:
print(a["published_at"], a["host"], a["title"])JavaScript 示例
const url = new URL("https://freenewsapi.ai/v1/search");
url.search = new URLSearchParams({ q: "central bank", date: "24h", size: "20" });
const { results } = await (await fetch(url, { headers: { Authorization: `Bearer ${FNA_KEY}` } })).json();
results.forEach(a => console.log(a.published_at, a.host, a.title));