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

   Top up

   A new account gets 50 trial calls on any endpoint, counted only when a call returns data; after that, calls are paid from a prepaid balance. Top up in the console by card or Alipay (through Stripe), or with USDT (TRC-20): a card or Alipay payment is credited as soon as it succeeds, USDT about a minute after the transfer confirms. When the balance cannot pay for a call, nothing runs and you get 402 insufficient_balance.

   Top up
3. 3

   Check the keyGET/v1/account

   Confirms the API key works and returns balance and plan. Not charged.

   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": null
       }
     },
     "meta": {
       "billed": false
     }
   }

4. 4

   Make your first call

   Try Bilibili video search (GET /v1/raw/bilibili/search): it serves live data at $0.0005 per successful call.

   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": true,
       "charged_usd": "0.000500",
       "balance_usd": "9.999500",
       "empty": false
     }
   }

   Catalog sample, not live data

   Only a successful call that returns data is charged; its meta says what it cost and the balance left (charged_usd, balance_usd). Empty results and failures are not charged.

   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.
• Call the API from your server: browser requests from other sites are refused (CORS), so the key never has to sit in web page code.
• 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 in full:

{
  "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.000500",
    "balance_usd": "9.999500",
    "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 are not charged: the reserved charge is given back automatically.
• Calls are paid from a prepaid balance shared by every endpoint. Top up by card, Alipay or USDT (TRC-20); it is credited automatically.
• 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.

Accounts and endpoints

No rate limits

• No rate limits: Qovia does not limit requests per minute per account or per endpoint. Only repeated failed authentication from one IP is throttled (429 `too_many_auth_failures`).
• 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": "insufficient_balance",
    "message": "insufficient balance for this request",
    "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: