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

开始使用

API 快速入门

通过 HTTP 直接调用 Google 搜索与 YouTube API。发送一次请求并读取 JSON 响应,无需 SDK。

  1. 认证

    创建账户、验证邮箱,并创建具有 Google 搜索权限的 API Key。已有密钥可直接使用。

    在终端运行命令,在隐藏输入提示中粘贴密钥。已设置 FLASHDATA_API_KEY 时可跳过。

    设置密钥
    # Bash: paste the key into a hidden prompt, not into this command.
    read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
    printf '\n'
    export FLASHDATA_API_KEY
  2. 执行搜索

    选择客户端,在同一终端运行示例。每个示例向 https://data.flashdata.dev/v1/queries/realtime 发送一次 POST 请求并输出 JSON。使用 X-API-Key 认证,以 Content-Type: application/json 发送 JSON。

    cURL 7.76+ · 在 Linux、macOS 或 Git Bash 中粘贴运行。

    搜索 · Bash / cURL
    curl --fail-with-body --silent --show-error --max-time 70 \
      --request POST https://data.flashdata.dev/v1/queries/realtime \
      --header "X-API-Key: $FLASHDATA_API_KEY" \
      --header 'Content-Type: application/json' \
      --data '{
      "source": "google_search",
      "query": "battery recycling research",
      "params": {
        "num": 5
      }
    }'
  3. 检查结果

    确认 HTTP 成功且 status 为 done。在 results[].organic 读取来源标题、链接及摘要,通过 usage.credits 查看扣费。

    status 为 done 时,results 或 organic 列表为空可以表示有效空结果。

    响应示例
    {
      "source": "google_search",
      "status": "done",
      "results": [
        {
          "organic": [
            {
              "title": "Battery recycling research",
              "link": "https://example.org/recycling",
              "snippet": "An example search excerpt."
            }
          ]
        }
      ],
      "usage": {
        "credits": 0.02
      }
    }
    status
    "done" 表示查询成功完成。
    results[0].organic[]
    搜索结果。按索引读取前先确认 results 非空。
    title / link / snippet
    来源标题、URL 及摘要。
    usage.credits
    本次查询实际消耗的 Credits。

保存响应以排查问题

要保存下一次预期请求,在上方 cURL 命令后添加以下选项。决定重试前先检查保存的文件。

cURL
--dump-header response-headers.txt --output result.json

检查权限与 Credits

这些 GET 请求读取身份、余额及价格,不消耗查询 Credits。预期返回 HTTP 200,提交付费任务前请检查下方字段。

账户读取:https://api.flashdata.dev/v2。数据请求:https://data.flashdata.dev/v1。两者使用 X-API-Key;JSON POST 请求还使用 Content-Type: application/json。

免费检查 · Bash
(
for endpoint in 'identity' 'balance' 'pricing?source=google_search&request_count=1'; do
  printf '\n%s\n' "$endpoint"
  curl --fail-with-body --silent --show-error --max-time 20 \
    --header "X-API-Key: $FLASHDATA_API_KEY" \
    --write-out '\nHTTP %{http_code}\n' \
    "https://api.flashdata.dev/v2/api-access/$endpoint" || exit
done
)
identity
确认 accountId 属于预期账户,access 为 "ready",scopes 包含 "google_search",并检查 expiresAt。所有者密钥的 accountType 为 "owned",试用密钥为 "temporary"。
balance
读取 availableCredits。此账户的所有密钥共用该余额。
pricing
确认 prices[0] 的 source 为 google_search,available 为 true。将 requestCount: 1 对应的 estimatedCredits 与 availableCredits 比较。提交前价格及余额仍可能变化。

下一步

步骤失败时

读取终端输出的响应。JavaScript 和 Python 将 HTTP 错误及 Retry-After 输出到 stderr。每个示例仅提交一次,不自动重试。

找不到命令或不支持选项
检查所选示例要求的版本。使用 PowerShell 7 而非 Windows PowerShell 5.1,或使用 Bash 与 cURL 7.76+。JavaScript 需要 Node 22+,Python 需要 3.10+。从官方页面安装缺少的运行环境,重开终端后重新设置密钥。
缺少密钥 / 401
在当前进程设置 FLASHDATA_API_KEY,再检查 identity。提供完整有效 API Key,不添加 Bearer 前缀。若已到期或被撤销,使用当前授权凭据,不要粘贴到聊天。
403
检查 identity.scopes 是否包含 google_search,access 是否为 ready。向所有者申请缺失权限;修改请求 source 不会授予权限。
402
重新读取余额并与当前价格比较。所有者可检查 Billing。试用耗尽后需通过认领获得所有者访问,创建替代试用不是恢复方式。
400 / 422
读取返回的错误信息,检查数据域名、POST 方法、Content-Type 和 JSON 字段名。使用英文直引号及数字类型 params.num,修正被拒绝的请求。
429
若返回 Retry-After,请遵守;否则采用有限退避并降低并发。不要快速循环、创建新密钥或注册新试用绕过限流。
HTTP 200 但状态失败或包含错误
读取响应体中的错误,保留返回的请求或任务 ID。成功解析 JSON 不等于任务成功,不要自动重提。
结果为空
若 status 为 done,认证已成功。保留空结果,或将更宽泛的查询作为新的付费请求。
超时、连接中断、5xx 或返回 HTML
POST 可能已被接受,即使响应丢失。决定重发前,在 History 检查原查询并保留返回的 ID。免费 GET 检查可以重试。确认 URL 使用 data.flashdata.dev 而非网站域名,不要关闭 TLS 验证。