快速开始

1. 1

   创建 API Key

   在控制台创建 API Key，可以限定它能调用的接口（scope）。完整的 Key 只在创建时显示一次，请马上保存：服务端只保存它的哈希，之后无法再查看。

   终端

   export QOVIA_KEY="sk-qovia-…"

   Key 的格式是 sk-qovia- 加 43 位字母和数字。创建 API Key

2. 2

   验证 KeyGET/v1/account

   确认 API Key 可用，并返回余额、套餐、每分钟上限和本月免费额度。不扣费，但计入限流。

   cURL

   curl https://api.qovia.ai/v1/account \
     -H "Authorization: Bearer $QOVIA_KEY"

   示例响应

   {
     "request_id": "00000000-0000-0000-0000-000000000000",
     "data": {
       "user": {
         "id": "00000000-0000-0000-0000-000000000000",
         "email": "you@example.com"
       },
       "api_key": {
         "id": "00000000-0000-0000-0000-000000000000",
         "name": "production",
         "scopes": [
           "*"
         ],
         "expires_at": null
       },
       "billing": {
         "balance_usd": "10.000000",
         "plan": "payg",
         "rpm_limit": 600,
         "free_quota": {
           "limit": 1000,
           "used": 12,
           "remaining": 988,
           "resets_at": "2026-11-01T00:00:00+08:00"
         }
       }
     },
     "meta": {
       "billed": false
     }
   }

3. 3

   发起第一次调用

   用「B 站视频搜索」（GET /v1/raw/bilibili/search）试一下：它返回实时数据，并且可以用免费额度。

   cURLPythonJavaScriptHTTP

   curl 'https://api.qovia.ai/v1/raw/bilibili/search?keyword=%E5%8F%B0%E7%A7%AF%E7%94%B5' \
     -H "Authorization: Bearer $QOVIA_KEY"

   把 $QOVIA_KEY 换成你的 API Key

   示例响应200 OK

   JSON结构

   {
     "request_id": "00000000-0000-0000-0000-000000000000",
     "data": {
       "items": [
         {
           "id": "soc_bil_2913ac9c522a",
           "src": "social",
           "platform": "bilibili",
           "lang": "zh-CN",
           "text": "「小白」全球芯片代工王！万字台积电发展史",
           "author": {
             "uid_hash": "ca5fa000e345",
             "mid": "8969156",
             "name": "小白测评"
           },
           "metrics": {
             "plays": 689248,
             "likes": 20365,
             "saves": 7230,
             "comments": 1348,
             "danmaku": 2676
           },
           "extra": {
             "source_id": "BV1DkoeYhExZ",
             "url": "https://www.bilibili.com/video/BV1DkoeYhExZ",
             "title": "「小白」全球芯片代工王！万字台积电发展史",
             "published_at": "2025-03-26T18:30:00+08:00",
             "category": {
               "id": 95,
               "name": "数码"
             },
             "tags": [
               "芯片",
               "数码",
               "台积电",
               "手机芯片"
             ],
             "cover": "https://i0.hdslb.com/bfs/archive/8f62d780e4e308bafa8c9f6c4d14ce5a28b2ce0b.jpg"
           },
           "prov": {
             "hash": "0xc16f694e973143c1",
             "ts": "2026-10-20T12:00:00+08:00",
             "source": "live"
           }
         }
       ],
       "cursor": 2,
       "has_more": true
     },
     "meta": {
       "billed": false,
       "charged_usd": "0.000000",
       "used_free_quota": true,
       "free_quota_remaining": 999,
       "balance_usd": "0.000000",
       "empty": false
     }
   }

   目录示例，不是实时数据

   新账户的前 1,000 次调用走免费额度，不扣费；额度用完后同样的调用按价格扣费，meta 见下方「响应」一节的示例。

   查看这个接口的完整参考

所有接口都在同一个基础地址下：

每个请求都在 Authorization 请求头里用 Bearer 方式带上 API Key：

Authorization: Bearer $QOVIA_KEY

• 也可以改用 x-api-key: <API Key> 请求头；两个都带时以 Authorization 为准。
• 服务端只从这两个请求头读取 Key，从不读取 URL 参数或 Cookie。
• 缺少、格式不对、已吊销或已过期的 Key 返回 401 invalid_api_key；同一 IP 一分钟内认证失败 30 次后返回 429 too_many_auth_failures。

权限范围（scope）

创建 Key 时可以选择一个或多个 scope；调用 Key 权限之外的接口返回 403 scope_denied。

GET 接口

参数放在查询串里，按参数类型转换：整数直接写数字，布尔值接受 true / false / 1 / 0 / yes / no，数组重复参数名传多个值（?id=1&id=2）。

POST 接口

请求体是一个 JSON 对象，带上 Content-Type: application/json。不是合法 JSON 或不是对象时返回 400 invalid_params。

参数校验

只接受接口列出的参数。多出的参数、缺少必填、类型或格式不对都返回 400 invalid_params，不扣费；message 以出错的参数名开头（item_id: …），缺少必填或多出参数时以 params: … 开头。

默认值

可选参数不传时，由服务端补上默认值（见各接口参数的「默认」）。

成功返回 HTTP 200 和统一信封。下面是免费额度用完之后的一次扣费调用，可以和第 3 步对照：

{
  "request_id": "00000000-0000-0000-0000-000000000000",
  "data": {
    "items": [
      {
        "id": "soc_bil_2913ac9c522a",
        "src": "social",
        "platform": "bilibili",
        "lang": "zh-CN",
        "text": "「小白」全球芯片代工王！万字台积电发展史",
        "author": {
          "uid_hash": "ca5fa000e345",
          "mid": "8969156",
          "name": "小白测评"
        },
        "metrics": {
          "plays": 689248,
          "likes": 20365,
          "saves": 7230,
          "comments": 1348,
          "danmaku": 2676
        },
        "extra": {
          "source_id": "BV1DkoeYhExZ",
          "url": "https://www.bilibili.com/video/BV1DkoeYhExZ",
          "title": "「小白」全球芯片代工王！万字台积电发展史",
          "published_at": "2025-03-26T18:30:00+08:00",
          "category": {
            "id": 95,
            "name": "数码"
          },
          "tags": [
            "芯片",
            "数码",
            "台积电",
            "手机芯片"
          ],
          "cover": "https://i0.hdslb.com/bfs/archive/8f62d780e4e308bafa8c9f6c4d14ce5a28b2ce0b.jpg"
        },
        "prov": {
          "hash": "0xc16f694e973143c1",
          "ts": "2026-10-20T12:00:00+08:00",
          "source": "live"
        }
      }
    ],
    "cursor": 2,
    "has_more": true
  },
  "meta": {
    "billed": true,
    "charged_usd": "0.001500",
    "used_free_quota": false,
    "free_quota_remaining": 0,
    "balance_usd": "9.998500",
    "empty": false
  }
}

成功响应

错误响应

响应头

/v1 只接受 GET 和 POST：其他方法（如 PUT、DELETE）由框架直接返回 405 {"detail": "Method Not Allowed"}；服务端意外错误可能是纯文本 500。这两种都不扣费。

• 只有成功并且有结果的调用才扣费。
• 失败、空结果、超时一律不扣费：预扣的费用和免费次数会自动退回。
• 每月 1,000 次免费调用，按 Asia/Singapore 时区的自然月重置；只用于标注「可用免费额度」的接口，免费调用不计入阶梯。
• 余额不足以支付一次调用时，请求不会执行，返回 402 insufficient_balance。
• 每次的扣费写在 meta 和 X-Qovia-Charged / X-Qovia-Balance 响应头里。

阶梯价格

按产品的边际阶梯计价：同一个自然月里，超过阈值之后的计费调用按下一档价格计算。

固定价格的接口

下面这些接口不走阶梯，每次成功调用按固定价格扣费。

免费账户

60 次/分钟

首次充值后

600 次/分钟

计数窗口

60 秒滑动窗口

• 每分钟上限按账户计算：同一账户的所有 API Key 和控制台调试台共用。
• 部分接口另有全局每秒上限（所有用户合计，见各接口页的「限速」）；超过时返回 429 endpoint_busy，这次请求不占你的每分钟额度。
• 最近 10 分钟里打到数据源的请求，如果至少 50 次、且超过 80% 是空结果、不存在或被拒，返回 429 too_many_unbilled，放慢后再试。
• 429 或 503 响应带 Retry-After 响应头时，按它给出的秒数等待后再重试。503 endpoint_unavailable 不带这个头：接口暂未上线，重试也不会成功。

出错时返回对应的 HTTP 状态码和错误信封：

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded",
    "request_id": "00000000-0000-0000-0000-000000000000"
  }
}

请按 error.code 判断；message 只给人看，可能有多种写法。

AI 工具可以通过 MCP 直接调用这些接口；同一份目录也以机器可读的形式发布，可以交给代码生成器：