Quickstart

1. 1

   Create an API key

   Create a key in the console and, if you like, limit the endpoints it can call (scopes). The full key is shown once, when you create it, so save it right away: the server keeps only a hash and cannot show it again.

   Shell

   export QOVIA_KEY="sk-qovia-…"

   Keys look like sk-qovia- plus 43 letters and digits.Create an API key

2. 2

   Check the keyGET/v1/account

   Confirms the API key works and returns balance, plan, per-minute limit and this month's free quota. Free, but counts toward the rate limit.

   cURL

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

   Example response

   {
     "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

   Make your first call

   Try Bilibili video search (GET /v1/raw/bilibili/search): it serves live data and runs on the free quota.

   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"

   Replace $QOVIA_KEY with your API key

   Example response200 OK

   JSONTree

   {
     "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
     }
   }

   Catalog sample, not live data

   A new account's first 1,000 calls run on the free quota and cost nothing; after that the same call is charged at its price, as the meta of the paid example under Responses below shows.

   See this endpoint's full reference

Every endpoint lives under one base URL:

Send the API key with every request, as a Bearer token in the Authorization header:

Authorization: Bearer $QOVIA_KEY

• You can send x-api-key: <API Key> instead; when both are present, Authorization wins.
• The key is read from these two headers only, never from the URL or a cookie.
• A missing, malformed, revoked or expired key gets 401 invalid_api_key; 30 failed attempts from one IP within a minute get 429 too_many_auth_failures.

Scopes

A key carries one or more scopes, picked when you create it; calling an endpoint outside them gets 403 scope_denied.

GET endpoints

Parameters go in the query string and are converted to their declared types: integers as digits, booleans as true / false / 1 / 0 / yes / no, and arrays by repeating the name (?id=1&id=2).

POST endpoints

The body is one JSON object, sent with Content-Type: application/json. A body that is not valid JSON, or not an object, gets 400 invalid_params.

Validation

Only the listed parameters are accepted. An unknown one, a missing required one, or a wrong type or format gets 400 invalid_params, not charged. Its message starts with the parameter's name (item_id: …); a missing or unknown parameter starts it with params: ….

Defaults

Optional parameters you leave out get their defaults on the server (see each parameter's Default).

A success is HTTP 200 with the shared envelope. Here is a paid call, once the free quota is used up; compare it with step 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
  }
}

Success

Errors

Response headers

/v1 only takes GET and POST: other methods (e.g. PUT, DELETE) get a framework 405 {"detail": "Method Not Allowed"}, and an unexpected server error may be a plain-text 500. Neither is charged.

• Only successful calls that return data are charged.
• Failures, empty results and timeouts cost nothing: the reserved charge, or free call, is given back automatically.
• 1,000 free calls a month, reset each calendar month in Asia/Singapore, on endpoints marked "Free quota applies"; free calls do not count toward the tiers.
• When the balance cannot pay for a call, nothing runs and you get 402 insufficient_balance.
• Every call reports its charge in meta and in the X-Qovia-Charged / X-Qovia-Balance headers.

Tiered prices

Each product is priced in marginal monthly tiers: within a calendar month, billed calls past a threshold are priced at the next tier.

Fixed-price endpoints

These endpoints are not tiered: every successful call costs a fixed price.

Free accounts

60 req/min

After the first top-up

600 req/min

Window

60 s, sliding

• The per-minute limit is per account: all its API keys and the console playground share it.
• Some endpoints also have a global per-second cap (across all users; see each endpoint's Rate cap); over it you get 429 endpoint_busy, and the request does not count toward your per-minute limit.
• If, in the last 10 minutes, at least 50 of your calls to data sources, and over 80% of them, came back empty, not found or rejected, you get 429 too_many_unbilled; slow down and retry.
• When a 429 or 503 carries a Retry-After header, wait that many seconds before you retry. A 503 endpoint_unavailable has none: the endpoint is not live, so retrying will not help.

An error comes with its HTTP status and the error envelope:

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

Branch on error.code; message is for people and can be worded several ways.

AI tools can call these endpoints directly over MCP, and the same catalog is published in machine-readable form for code generators: