浏览文档
API 参考
为应用选择结构化 JSON,为智能体选择 Markdown 正文。通过两个请求头控制响应。
本页内容
选择格式
默认返回保留原始结果字段的 JSON。Accept 选择 JSON 或纯文本;X-Respond-With: markdown 将结果正文转换为 Markdown。请求体仍使用 JSON。
| 响应 | Accept | X-Respond-With | 适用于 |
|---|---|---|---|
| JSON | application/json | 省略 | 在代码中解析字段 · 默认 |
| JSON + Markdown | application/json | markdown | 智能体上下文及结构化元数据 |
| 纯文本 | text/plain | 省略 | 在终端阅读原始字段 |
| 文本 + Markdown | text/plain | markdown | 一起阅读元数据和 Markdown |
请求与响应示例
以下标签展示同一次 Google 搜索的不同格式。使用 Bash 和 cURL 7.76+,并将 FLASHDATA_API_KEY 设为具备 google_search 权限的密钥。每次执行命令会提交一次计费搜索。
默认格式。解析 results 数组,数组内的字段由具体来源决定。
curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{"source":"google_search","query":"vector databases"}'{
"source": "google_search",
"status": "done",
"results": [
{
"organic": [
{
"title": "Example page",
"link": "https://example.com/article",
"snippet": "A short source snippet."
}
]
}
],
"usage": {
"credits": 0.01
},
"created_at": "2026-10-22T12:00:00.000Z"
}读取 content 中的 Markdown 字符串。它替代 results;source、status、usage 仍保留为 JSON 字段。
curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-Respond-With: markdown' \
--data '{"source":"google_search","query":"vector databases"}'{
"source": "google_search",
"status": "done",
"usage": {
"credits": 0.01
},
"created_at": "2026-10-22T12:00:00.000Z",
"content": "# Google search\n\n## Organic\n\n### 1. Example page\n\n**Link:** <https://example.com/article>\n\n**Snippet:** A short source snippet\\.\n"
}按文本读取响应。原始字段以缩进形式展示,不是 JSON 文档。
curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--data '{"source":"google_search","query":"vector databases"}'Source: "google_search"
Status: "done"
Results:
1:
Organic:
1:
Title: "Example page"
Link: "https://example.com/article"
Snippet: "A short source snippet."
Usage:
Credits: 0.01
Created at: "2026-10-22T12:00:00.000Z"
按文本读取响应:先显示元数据,再显示 Markdown 正文。
curl --fail-with-body --silent --show-error \
'https://data.flashdata.dev/v1/queries/realtime' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--header 'X-Respond-With: markdown' \
--data '{"source":"google_search","query":"vector databases"}'Source: "google_search"
Status: "done"
Usage: {"credits":0.01}
Created at: "2026-10-22T12:00:00.000Z"
Markdown Content:
# Google search
## Organic
### 1. Example page
**Link:** <https://example.com/article>
**Snippet:** A short source snippet\.
支持的端点
这些规则适用于 Google 搜索和 YouTube 查询来源。对于 YouTube 下载,转换的是交付记录,不是视频或音频字节。账户 API、Bulk 清单与 NDJSON 分片、回调及 MCP 响应使用各自的格式。
| 端点 | JSON / 纯文本 | Markdown 正文 |
|---|---|---|
| POST /v1/queries/realtime | 支持 | 支持 |
| GET /v2/jobs/{id}/results | 支持 | 支持 |
| POST /v1/queries | 提交回执 | 忽略 — 读取结果时设置 |
| POST /v1/queries/batch | 提交回执 | 忽略 — 读取结果时设置 |
| GET /v2/jobs/{id} | 任务状态 | 忽略 — 此处不包含结果正文 |
选择已完成任务的结果格式
读取结果时设置请求头;提交时设置的格式不会保留。将 JOB_ID 设为你有权访问的已完成任务 ID。此 GET 读取已有结果,不会重新提交查询。
| 请求格式 | 结果响应 |
|---|---|
| 原始 JSON | 302,Location 包含签名存储 URL。单独获取该 URL,不附带 X-API-Key。存储结果可能经过 gzip 压缩。 |
| 纯文本或任一 Markdown 选项 | 200,响应体直接包含格式化结果。 |
curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/jobs/${JOB_ID:?Set JOB_ID}/results" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Accept: application/json' \
--header 'X-Respond-With: markdown'格式错误
即使请求纯文本,API 错误仍返回 JSON 或 application/problem+json。解析成功响应格式前先检查 HTTP 状态。
| 状态 / 错误码 | 修正方法 |
|---|---|
| 400 · unsupported_representation | 使用 X-Respond-With: markdown 或省略该请求头。不支持 json、text 等值。 |
| 406 · not_acceptable | 使用 Accept: application/json 或 text/plain。不支持 text/markdown 和 application/xml。 |
Accept 请求头细节
省略 Accept 或发送 */* 时返回 JSON。响应使用 UTF-8。支持媒体范围和 q 权重;不支持的字符集返回 406,除非匹配到其他可接受的范围。Content-Type: application/json 描述请求体,不控制响应。
Accept: text/plain; charset=utf-8, application/json;q=0.8