Tabicon API Documentation

Fetch icons from any website with one GET request. Suitable for directory sites, content aggregators, CMS backends, and SaaS consoles. Structured by parameters, examples, and status codes for efficient integration.

Quick Start Get API Key

Quick Start

Successful requests return image/png and can be used directly as an URL. Validation failures return corresponding status codes and plain-text reasons. Accessing /api/get without url returns service health text.

Get API Key

By default, sign up and create an API key in the console first. You can leave it empty only when guest mode is enabled and a default demo key is configured.

Build Request

Send a GET request to /api/get. url is required; size is optional and unsupported values fall back to 64; key can be passed as a query parameter or via the X-API-Key header.

Handle Response

Successful response returns image/png icon data, ready for tags.

Error Handling

Failed requests return status codes; see Response Status section for details.

Endpoint

Use the following endpoint to fetch website icons.

GET https://www.favicon.org.cn/api/get?url={domain}[&size={size}][&key={api_key}]

💡 Tip

You may omit the key only when guest mode is enabled and a default demo key is configured. In production, explicitly send a valid API key.

Parameters

The API supports the following query parameters.

url Required

Target domain or URL, e.g. `apple.com` or `https://github.com`.

size Optional

Output size supports `16/32/48/64/96/128/256/512`. Default is `64`; unsupported values automatically fallback to `64`.

key Optional

API key. A valid key is required by default; it becomes optional only when guest mode is enabled and a default demo key is configured. The API also accepts X-API-Key header input.

Authentication

The API accepts the key either as a query parameter or as a request header. For production, prefer the header form.

Option 1: Query Parameter

Best for direct image URLs such as frontend , static pages, or simple scripts.

Query

https://www.favicon.org.cn/api/get?url=example.com&size=128&key=YOUR_API_KEY

Option 2: X-API-Key Header

Best for server-side requests, proxy forwarding, or any case where you do not want the key exposed in the URL.

cURL

curl -H "X-API-Key: YOUR_API_KEY" "https://www.favicon.org.cn/api/get?url=example.com&size=128"

JavaScript / fetch

const response = await fetch('https://www.favicon.org.cn/api/get?url=example.com&size=128', {
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  }
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const blob = await response.blob();
document.getElementById('favicon').src = URL.createObjectURL(blob);

💡 Tip

The endpoint reads ?key=... first. If it is missing, it then checks the X-API-Key header. When guest mode is enabled and a default demo key is configured, you may also test without sending a key.

Response Status

The API may return the following HTTP status codes.

200 Request succeeded; returns `image/png` icon data.
400 Invalid parameter: malformed `url`.
403 Unauthorized or policy rejected (missing/invalid key, guest access disabled, private-network URL, whitelist mismatch, or permission validation failure).
404 No available icon found on target site.
426 Target policy requires HTTPS.
429 Too many requests. Please retry later.
500 Internal service error (cache path/write failure).

Code Examples

The following examples show how to integrate the API in your project.

HTML

<img src="https://www.favicon.org.cn/api/get?url=example.com&size=128&key=YOUR_API_KEY" alt="Favicon of example.com" />

JavaScript

const url = 'https://www.favicon.org.cn/api/get?url=example.com&size=128&key=YOUR_API_KEY';
document.getElementById('favicon').src = url;

PHP

$url = 'https://www.favicon.org.cn/api/get?' . http_build_query([
    'url' => 'example.com',
    'size' => 128,
    'key' => 'YOUR_API_KEY'
]);
echo '<img src="' . htmlspecialchars($url) . '" alt="Favicon of example.com">';

Back to Home

Return to home to explore more features.