介绍
Prismfy 通过一个 REST 接口 POST /v1/search，为 AI 智能体和自动化工作流提供同步的公开网页搜索。
⚡
单一接口
只用 POST /v1/search 即可
🧰
结构化 JSON 响应
返回 title、URL、snippet、engine 与元数据，便于工具调用
🔄
缓存命中免费
命中缓存不会消耗配额
基础 URL
https://api.prismfy.io所有请求都必须通过 HTTPS 发起。HTTP 请求会被拒绝，API 所有响应均为 JSON。
快速开始
不到一分钟拿到你的第一批搜索结果：
1
创建账户
前往 prismfy.io/register 注册，无需信用卡。
2
复制你的 API 密钥
完整密钥只会在创建时显示一次。请妥善保存，之后无法再次查看完整值。
3
发起第一次请求
可使用任意 HTTP 客户端，请把 API 密钥放进 Authorization 请求头。
cURL
# 第 1 步 —— 注册并在控制台获取你的 API 密钥
# 第 2 步 —— 发起第一次搜索请求：
curl -X POST https://api.prismfy.io/v1/search \
-H "Authorization: Bearer ss_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "hello world"}'认证方式
所有受保护接口都要求携带 Authorization 请求头：
http
Authorization: Bearer <token>使用 API 密钥
这是服务端代码最简单的认证方式。API 密钥以 ss_live_ 开头，除非你手动删除，否则不会过期。
bash
curl https://api.prismfy.io/v1/search \
-H "Authorization: Bearer ss_live_YOUR_KEY" \
...POST /v1/search
这是主搜索接口。它是同步的，结果准备好后直接返回。如果相同查询已命中缓存，会立即返回 cached: true，并且不消耗配额。
POST
/v1/search在一个或多个受支持引擎上执行搜索
ℹ️在当前共享余额模型下，计费粒度按 API 请求计算。 一次
POST /v1/search 在未命中缓存时只消耗一次请求，与选择了哪些引擎无关。缓存命中免费。cURL
curl -X POST https://api.prismfy.io/v1/search \
-H "Authorization: Bearer ss_live_••••••••••••" \
-H "Content-Type: application/json" \
-d '{
"query": "typescript best practices",
"engines": ["brave", "bing"],
"language": "en",
"page": 1
}'请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
query | string | ✅ | 搜索查询，长度 1–500 个字符。 |
page | number | — | 结果页码（默认 1）。最大值取决于套餐。 |
engines | string[] | — | 要查询的引擎。默认值：["brave", "bing"].免费套餐：默认使用 brave 与 bing，也可请求全部引擎，包括 Google。免费账户整体限制为 10 RPM，部分引擎可能还有更严格的子限制。实时引擎目录：调用 GET /v1/plans，查看当前环境下的 allEngines、defaultEngines 与 allowedEngines。 |
language | string | — | 语言代码，例如 en, ru, de. |
timeRange | string | — | day / week / month / year |
domain | string | — | 限制到指定域名，会自动把 site:domain 添加到查询中。 |
响应格式
成功响应一定包含 results 与 cached。当 cached 为 true 时，响应会返回一个精简版的 meta 对象，仅保留请求形态字段；像 taskId、durationMs 与 provider 这样的执行字段会被省略。
json
{
"results": [
{
"title": "TypeScript Best Practices 2026",
"url": "https://example.com/typescript",
"content": "A short snippet of the page content...",
"engine": "brave"
}
],
"cached": false,
"query": "typescript best practices",
"meta": {
"taskId": "550e8400-e29b-41d4-a716-446655440000",
"durationMs": 1243,
"provider": "prismfy",
"engines": ["brave", "bing"],
"page": 1,
"language": "en",
"timeRange": "month",
"domain": null
}
}| 字段 | Type | 说明 |
|---|---|---|
results[].title | string | 页面标题 |
results[].url | string | 规范 URL |
results[].content | string | 页面内容摘要 |
results[].engine | string | 该结果来自哪个引擎 |
cached | boolean | true 表示命中缓存返回（不收费） |
meta.taskId | string | 唯一搜索任务 ID。缓存命中时省略。 |
meta.durationMs | number | 搜索耗时（毫秒）。缓存命中时省略。 |
meta.provider | string | 存在执行元数据时显示 provider 标签。缓存命中时省略。 |
套餐限制
| 套餐 | 最大页数 | RPM | 配额 | 默认引擎 |
|---|---|---|---|---|
| 免费套餐 | 1 | 10 | 1,000 次一次性请求 | brave, bing |
| Pro | 10 | 60 | 每月 3,500 次请求 | brave, bing |
| Data Digger | 10 | 120 | 每月 10,000 次请求 | brave, bing |
| Enterprise | 20 | 300 | 定制 | 全部引擎 |
GET /v1/user/me
返回完整用户资料，包括当前共享请求余额与配额使用情况。可用于在控制台展示套餐和用量状态。
GET
/v1/user/me完整资料 + 配额
json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "user@example.com",
"tier": "free",
"balance": {
"shared": {
"remaining": 953,
"expiresAt": null,
"expired": false
}
},
"quota": {
"total": 1000,
"used": 47,
"remaining": 953,
"expiresAt": null,
"expired": false
},
"isActive": true,
"createdAt": "2026-03-05T16:27:53.678Z"
}GET /v1/user/me/searches
分页返回用户最近的搜索查询，可用于控制台中的“最近搜索”组件。
GET
/v1/user/me/searches分页搜索历史
| 查询参数 | Default | Max | 说明 |
|---|---|---|---|
limit | 20 | 100 | 返回结果数量 |
offset | 0 | 100,000 | 跳过指定条数（分页） |
json
{
"searches": [
{
"id": "uuid",
"taskId": "uuid",
"query": "best typescript frameworks 2026",
"engines": ["brave", "bing"],
"status": "success",
"durationMs": 1243,
"createdAt": "2026-03-05T14:23:11.000Z"
}
],
"limit": 20,
"offset": 0
}GET /v1/user/me/usage
事件日志：包括配额扣减、套餐升级、管理员调整等。
GET
/v1/user/me/usage配额事件日志
| 事件 | 时间 |
|---|---|
request_used | 一次成功搜索，已扣减配额 |
quota_set | 配额被手动修改（升级、管理员操作） |
API 密钥
每个用户最多可创建 10 个 API 密钥。完整密钥值只会在创建时显示 一次。之后只能看到元数据（名称、最近使用时间等）。
列出密钥
GET
/v1/user/me/keys返回所有密钥（仅元数据，不含原始值）
json
{
"keys": [
{
"id": "uuid",
"name": "Default",
"lastUsedAt": "2026-03-05T14:23:11.000Z",
"expiresAt": null
},
{
"id": "uuid",
"name": "Production Server",
"lastUsedAt": "2026-03-04T09:00:00.000Z",
"expiresAt": null
}
]
}创建密钥
POST
/v1/user/me/keys创建新密钥 —— 原始值只会出现在这次响应里
json
// 请求体
{ "name": "Production Server" }
// 成功响应 201
{
"id": "uuid",
"name": "Production Server",
"key": "ss_live_a1b2c3d4...",
"expiresAt": null
}⚠️
key 字段只会在 本次响应中返回一次。请安全保存，之后无法再次取回。如需轮换密钥，请创建新的并删除旧的。删除密钥
DELETE
/v1/user/me/keys/:id永久删除并立即使该密钥失效
json
// 成功响应 200
{ "success": true }
// 404 响应：Key 不存在或不属于当前用户
{ "error": "Not found", "code": "NOT_FOUND" }ℹ️删除会 立即生效 —— 密钥会在毫秒级从缓存中移除。任何仍在进行中的请求如果使用了被删除的密钥，都会被拒绝。
密钥轮换
建议定期轮换密钥以降低泄露风险。安全的轮换方式如下：
cURL
# 第 1 步：创建新密钥
curl -X POST https://api.prismfy.io/v1/user/me/keys \
-H "Authorization: Bearer ss_live_OLD_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Production v2"}'
# 第 2 步：从响应中复制新密钥（完整值只显示一次）
# 第 3 步：删除旧密钥
curl -X DELETE https://api.prismfy.io/v1/user/me/keys/KEY_ID \
-H "Authorization: Bearer ss_live_OLD_KEY"错误处理
所有错误都会返回统一的 JSON 结构：
json
{
"error": "Human-readable message",
"code": "MACHINE_READABLE_CODE"
}错误代码
| HTTP | code | 原因 | 处理建议 |
|---|---|---|---|
| 400 | VALIDATION_ERROR | 请求体无效 | 向用户展示错误信息 |
| 400 | INVALID_JSON | 空请求体或 JSON 格式错误 | 检查 Content-Type: application/json |
| 400 | INVALID_ENGINES | 你当前套餐不允许使用所请求的全部引擎 | 检查错误响应中的 allowedEngines 数组 |
| 401 | UNAUTHORIZED | token 缺失、已过期或无效 | 跳转到登录 |
| 402 | PAYMENT_REQUIRED | 配额已用尽或已过期 | 展示升级提示或当前余额状态 |
| 404 | NOT_FOUND | 资源不存在 | 显示 404 提示 |
| 429 | RATE_LIMIT_EXCEEDED | 请求过多 | 等待 retryAfter 秒 |
| 504 | TIMEOUT | 搜索耗时超过 30 秒 | 重试请求 |
| 500 | INTERNAL_ERROR | 服务器错误 | 展示通用错误信息 |
速率限制
触发速率限制时，响应会包含 retryAfter 字段（秒）以及 Retry-After HTTP 头：
json
{
"error": "请求过多",
"code": "RATE_LIMIT_EXCEEDED",
"retryAfter": 47
}| 套餐 | 速率限制 |
|---|---|
| 免费套餐 | 10 次请求 / 分钟 |
| Pro | 60 次请求 / 分钟 |
| Data Digger | 120 次请求 / 分钟 |
| Enterprise | 300 次请求 / 分钟 |
快速参考
BASE URL https://api.prismfy.io ── Public ──────────────────────────────────── GET /v1/plans 套餐与限制 ── Search ──────────────────────────────────── POST /v1/search 执行搜索 ── User ────────────────────────────────────── GET /v1/user/me 资料 + 配额 GET /v1/user/me/searches 搜索历史 GET /v1/user/me/usage 配额事件日志 GET /v1/user/me/keys 列出 API 密钥 POST /v1/user/me/keys 创建 API 密钥 DEL /v1/user/me/keys/:id 删除 API 密钥