跳转到正文
中文
获取 API 密钥
浏览文档

API 参考

响应格式

为应用选择结构化 JSON,为智能体选择 Markdown 正文。通过两个请求头控制响应。

本页内容

选择格式

默认返回保留原始结果字段的 JSON。Accept 选择 JSON 或纯文本;X-Respond-With: markdown 将结果正文转换为 Markdown。请求体仍使用 JSON。

响应AcceptX-Respond-With适用于
JSONapplication/json省略在代码中解析字段 · 默认
JSON + Markdownapplication/jsonmarkdown智能体上下文及结构化元数据
纯文本text/plain省略在终端阅读原始字段
文本 + Markdowntext/plainmarkdown一起阅读元数据和 Markdown

请求与响应示例

以下标签展示同一次 Google 搜索的不同格式。使用 Bash 和 cURL 7.76+,并将 FLASHDATA_API_KEY 设为具备 google_search 权限的密钥。每次执行命令会提交一次计费搜索。

默认格式。解析 results 数组,数组内的字段由具体来源决定。

请求 · cURL / Bash
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"
}

支持的端点

这些规则适用于 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 读取已有结果,不会重新提交查询。

请求格式结果响应
原始 JSON302,Location 包含签名存储 URL。单独获取该 URL,不附带 X-API-Key。存储结果可能经过 gzip 压缩。
纯文本或任一 Markdown 选项200,响应体直接包含格式化结果。
获取 JSON 中的 Markdown · cURL / Bash
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 描述请求体,不控制响应。

优先文本,也接受 JSON
Accept: text/plain; charset=utf-8, application/json;q=0.8