> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hermai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Brand API

> 把公司域名或工作邮箱转成结构化的品牌资料。

Brand API 把公司域名或工作邮箱转成结构化的品牌资料：名称、描述、logo、颜色、社交账号和主要链接。返回的每个字段都附有自己的来源，你的产品可以显示每个值是从哪里来的。

把域名或邮箱发送到 `POST /v1/brand/retrieve`。Hermai 有近期的资料时会返回缓存，没有时会启动新的提取。

## 获取品牌资料

`domain` 和 `email` 只能二选一发送。

```bash theme={null}
export HERMAI_API_KEY="hm_sk_..."

curl -sS -X POST "https://api.hermai.ai/v1/brand/retrieve" \
  -H "Authorization: Bearer ${HERMAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"domain":"stripe.com"}'
```

发送 `email` 时，Hermai 只保留域名，绝不存储或转发邮箱的用户名部分。

### 请求内容

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `domain` | string | 二选一 | 公司域名。用这个字段或 `email`，不能同时用。 |
| `email` | string | 二选一 | 工作邮箱。用这个字段或 `domain`，不能同时用。个人邮箱服务的域名（例如 `gmail.com`）会被拒绝。 |
| `max_age_s` | integer | 否 | 可接受的最大缓存年龄，单位秒。低于方案下限的值会被 Hermai 提高到下限：免费方案 2,592,000 秒（30 天），付费方案 604,800 秒（7 天）。`refresh.clamped` 会报告 Hermai 是否提高了你的值。 |
| `wait_ms` | integer | 否 | 冷提取时等待多久才返回 pending 结果。默认 1500，最大 15000。设为 `0` 会立即返回 pending 结果。 |
| `include_synthesized` | boolean | 否 | 保留给未来选择加入生成字段变体之用，目前没有作用。 |
| `force_refresh` | boolean | 否 | 目前不提供。任何把它设为 `true` 的请求都会以 `BRAND_FORCE_REFRESH_FORBIDDEN` 失败。 |

## 响应

```json theme={null}
{
  "status": "ok",
  "requested": {
    "input_type": "domain",
    "domain": "stripe.com"
  },
  "resolved": {
    "canonical_domain": "stripe.com",
    "ambiguity": null,
    "redirect_terminal": "https://stripe.com"
  },
  "brand": {
    "name": {
      "value": "Stripe",
      "source": { "url": "https://stripe.com/", "signal": "json_ld" },
      "observed_at": "2026-08-18T16:41:47Z",
      "origin": "observed"
    },
    "description": {
      "value": "Stripe powers online and in-person payment processing and financial solutions for businesses of all sizes.",
      "source": { "url": "https://stripe.com/", "signal": "json_ld" },
      "observed_at": "2026-08-18T16:41:47Z",
      "origin": "observed"
    },
    "logos": [
      {
        "url": "https://api.hermai.ai/v1/brand/logo/61a219a0...",
        "kind": "wordmark",
        "theme": "light",
        "format": "svg",
        "width": 60,
        "height": 25,
        "source": { "url": "https://stripe.com/", "signal": "header_dom" },
        "observed_at": "2026-08-18T16:41:47Z",
        "origin": "observed"
      }
    ],
    "colors": [
      {
        "hex": "#031323",
        "role": "accent",
        "source": { "url": "https://stripe.com/", "signal": "header_dom" },
        "observed_at": "2026-08-18T16:41:47Z",
        "origin": "inferred"
      }
    ],
    "socials": [
      { "type": "twitter", "url": "https://twitter.com/stripe", "source": { "url": "https://stripe.com/", "signal": "json_ld" }, "observed_at": "2026-08-18T16:41:47Z", "origin": "observed" }
    ],
    "links": {
      "careers": { "value": "https://stripe.com/careers", "source": { "url": "https://stripe.com/", "signal": "header_dom" }, "observed_at": "2026-08-18T16:41:47Z", "origin": "observed" },
      "pricing": { "value": "https://stripe.com/pricing", "source": { "url": "https://stripe.com/", "signal": "header_dom" }, "observed_at": "2026-08-18T16:41:47Z", "origin": "observed" },
      "privacy": null,
      "terms": null,
      "contact": null,
      "blog": null
    }
  },
  "application_theme": {
    "version": "v1",
    "mode": "observed",
    "colors": { "action": "#031323", "on_action": "#FFFFFF", "text_accent": "#031323", "tint": "#E6E7E9", "on_tint": "#111827", "border": "#959CA3", "focus": "#031323", "data_primary": "#031323" },
    "identity": {
      "standard": { "asset": { "url": "https://api.hermai.ai/v1/brand/logo/61a219a0...", "kind": "wordmark" }, "show_company_name": false, "fallback": "none" },
      "compact": { "asset": null, "show_company_name": true, "fallback": "monogram" },
      "on_dark": { "asset": { "url": "https://api.hermai.ai/v1/brand/logo/cb86ad33...", "kind": "icon" }, "show_company_name": true, "fallback": "asset_with_company_name" }
    },
    "fallback": null
  },
  "assembled_at": "2026-08-18T16:41:47Z",
  "profile_generation": 1,
  "theme_readiness": "observed",
  "fallback_fields": ["accent"],
  "enrichment_status": "",
  "refresh": { "state": "stale", "clamped": false },
  "pending": null,
  "usage": { "credits_consumed": 1, "credits_remaining": 999 }
}
```

这个示例是对 `stripe.com` 的实际结果，为了篇幅有删节；实际调用会返回比这里更多的 logo、颜色、社交账号和链接。

### 顶层字段

| 字段 | 说明 |
| - | - |
| `status` | 这次查询的结果。见下方“状态值”。 |
| `requested` | 你发送的 `input_type`（`domain` 或 `email`）和值。 |
| `resolved` | Hermai 匹配到的规范域名，加上 `redirect_terminal`（Hermai 跟随重定向后最终落在的 URL）和 `ambiguity`。正常匹配时 `ambiguity` 为 `null`；`parked` 表示该域名是停放或待售页面，`multi_brand` 表示该域名承载一个以上的品牌，`unresolved` 表示 Hermai 无法确定是哪一家公司。 |
| `brand` | 品牌字段：`name`、`description`、`logos`、`colors`、`fonts`、`socials`、`links`。见下方“字段来源”。 |
| `application_theme` | 可直接用来在你的产品界面应用这家公司品牌的主题 token。Hermai 尚未推导出主题时不会出现。见下方“应用主题”。 |
| `assembled_at` | Hermai 组装这份响应的时间。 |
| `refresh` | `state` 为 `fresh`（在你的缓存窗口内）、`stale`（超过窗口，先返回最后一份已知资料，后台可能正在刷新）或 `refreshing`（后台刷新进行中）。Hermai 把你的 `max_age_s` 提高到方案下限时，`clamped` 为 `true`。 |
| `pending` | 只在 `status` 为 `pending` 时出现。带有 `poll_after_ms` 和用来轮询冷查询的 `token`。见下方“冷查询与轮询”。 |
| `usage` | 这次调用的 `credits_consumed` 和 `credits_remaining`。见下方“计费”。 |
| `profile_generation` | 每当 Hermai 观察到这家公司的标识有重大变动就会加一。用它判断你那边缓存的主题或 logo 是否需要刷新。 |
| `theme_readiness` | Hermai 为 `application_theme` 找到真实的 logo 和颜色证据时为 `observed`；你的产品应改用自己的主题时为 `fallback`。 |
| `fallback_fields` | 列出哪些主题输入退回了备用值，例如 `["accent"]` 或 `["logo"]`。`theme_readiness` 为 `observed` 时为空。 |
| `enrichment_status` | 报告可选的第二阶段样式处理。它绝不会延迟上面的响应。 |

## 字段来源

`brand` 里的每个字段都带有 Hermai 找到它的位置：

| 属性 | 说明 |
| - | - |
| `source.url` | Hermai 读到这个值的页面。 |
| `source.signal` | 承载这个值的信号，例如 `json_ld`、`header_dom`、`apple_touch_icon` 或 `manifest`。 |
| `observed_at` | Hermai 最后一次确认这个值的时间。 |
| `origin` | Hermai 得到这个值的方式。见下表。 |

`origin` 是以下之一：

| 值 | 含义 |
| - | - |
| `observed` | Hermai 直接从页面或结构化信号（例如 JSON-LD 或 manifest 文件）读到这个值。 |
| `inferred` | Hermai 从其他观察到的证据推导出这个值，例如从 logo 的主色计算出的强调色。 |
| `synthesized` | Hermai 生成了这个值，而不是从网站读取或推导。 |
| `corrected` | Hermai 用更好的值覆盖了质量不佳的观察值。 |

任何字段都没有置信度分数。请用 `origin` 和 `source` 判断一个值可信到什么程度。

## 描述

`description` 是公司自己撰写的简介，不是 Hermai 生成的摘要。Hermai 按下列优先顺序检查来源，采用第一个通过的：

1. JSON-LD 的 `Organization` 描述，且只在 JSON-LD 确认该组织属于所请求的域名时采用。未经确认的 JSON-LD 组织描述会被丢弃，不作为备用。
2. `og:description` meta 标签。
3. 普通的 `<meta name="description">` 标签。

Hermai 把描述限制在 500 字符内，并在该限制内最后一个完整句子的结尾截断，绝不补上省略号。

Hermai 会拒绝过短的文字、插页或机器人验证页面、cookie 与同意声明，以及堆砌关键词的文字。都不通过时，`description` 不会出现。

来自 `stripe.com` 的实际示例：

```json theme={null}
{
  "value": "Stripe powers online and in-person payment processing and financial solutions for businesses of all sizes.",
  "source": { "url": "https://stripe.com/", "signal": "json_ld" },
  "origin": "observed"
}
```

## 状态值

| 状态 | 含义 |
| - | - |
| `ok` | Hermai 找到完整可用的资料。 |
| `partial` | Hermai 找到部分可用的字段。 |
| `pending` | 提取仍在进行。见下方“冷查询与轮询”。 |
| `personal_email` | 这个邮箱属于常见的个人邮箱服务。 |
| `disposable_email` | 这个邮箱属于一次性邮箱服务。 |
| `not_found` | Hermai 无法解析出可用的公司域名。 |
| `fetch_failed` | Hermai 解析出域名但无法完成提取。封锁自动访问的网站会返回 `fetch_failed`。 |

## 冷查询与轮询

Hermai 已有新鲜资料的域名会立即返回，`status` 为 `ok`、`partial` 或其他终态值之一。

Hermai 近期没有提取过的域名会启动新的提取。若在 `wait_ms` 内没有完成，`POST /v1/brand/retrieve` 会返回 HTTP `202`，`status` 为 `pending`：

```json theme={null}
{
  "status": "pending",
  "pending": { "poll_after_ms": 1000, "token": "..." }
}
```

等待 `pending.poll_after_ms` 之后，带着 token 调用 `POST /v1/brand/poll`：

```bash theme={null}
curl -sS -X POST "https://api.hermai.ai/v1/brand/poll" \
  -H "Authorization: Bearer ${HERMAI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"token":"..."}'
```

响应持续返回 `202` 和 `status: pending` 时，用同一个 token 再轮询。token 的有效期是 5 分钟。提取完成后，poll 会返回 HTTP `200` 和完成的资料。

轮询本身免费。第一次送达终态结果时，不论来自 `retrieve` 还是 `poll`，都按下方的一般规则计费。

## 应用主题

`application_theme` 提供现成的 token，让你用这家公司的品牌来设计自己的产品，不必自己排序 logo 或挑选强调色。

| 字段 | 说明 |
| - | - |
| `colors` | 八个颜色 token：`action`、`on_action`、`text_accent`、`tint`、`on_tint`、`border`、`focus`、`data_primary`。 |
| `identity.standard` | 浅色背景用的主要 logo 位置。 |
| `identity.compact` | 适合小空间的 logo 位置，例如 favicon 大小的区域。 |
| `identity.on_dark` | 为深色背景挑选的 logo 位置。 |
| `mode` | 由真实证据建立时为 `observed`，否则为 `fallback`。 |

每个 identity 位置都带有 `asset`（一个 logo，或 `null`）、`show_company_name`（是否在素材旁一并显示公司名称）和 `fallback`（`asset` 为 `null` 时要显示什么，例如 `monogram` 或 `asset_with_company_name`）。

## 计费

成功的资料计 1 个普通 Hermai credit，与其他所有 Hermai 端点共用同一个 credit 池。`status` 为 `ok` 或 `partial`，且资料至少有名称、logo 或颜色其中之一时，Hermai 才计费。只有描述、社交账号或链接而没有名称、logo 或颜色的 `partial` 结果不计费。

Pending 结果和失败的查询一律不计费。

```json theme={null}
{
  "usage": { "credits_consumed": 1, "credits_remaining": 999 }
}
```

## 速率限制

Brand 端点叠加三层限制。由近期缓存资料响应的热请求只计入前两层；启动新提取的冷请求三层都计入。

与其他所有 Hermai 端点共用的每个 key 标准速率限制：

| 方案 | 每分钟 |
| - | - |
| Free | 20 |
| Starter | 60 |
| Pro | 100 |
| Enterprise | 120 |

Brand 专用的 workspace 限制，由 workspace 内所有 key 共用：

| 方案 | 每分钟 |
| - | - |
| Free | 10 |
| Starter | 60 |
| Pro | 200 |
| Enterprise | 200 |

仅应用于启动新提取的冷提取限制：

| 方案 | 每分钟 |
| - | - |
| Free | 5 |
| Starter | 20 |
| Pro | 50 |
| Enterprise | 50 |

三层中任何一层超过都会返回 HTTP `429`。

## 匿名 brand demo

`POST /v1/brand/demo` 不需要 API key、不消耗 credits 就能运行品牌查询。它只接受域名，返回较小的公开投影：`status`、`domain`，以及 `brand.name`、`brand.description`、`brand.logos`、`brand.colors`。它绝不返回 `socials`、`links` 或 `usage`。

```bash theme={null}
curl -sS -X POST "https://api.hermai.ai/v1/brand/demo" \
  -H "Content-Type: application/json" \
  -d '{"domain":"stripe.com"}'
```

```json theme={null}
{
  "status": "ok",
  "domain": "stripe.com",
  "brand": {
    "name": { "value": "Stripe", "origin": "observed" },
    "description": { "value": "Stripe powers online and in-person payment processing and financial solutions for businesses of all sizes.", "origin": "observed" },
    "logos": [ { "url": "https://api.hermai.ai/v1/brand/logo/61a219a0...", "kind": "wordmark" } ],
    "colors": [ { "hex": "#031323", "role": "accent" } ]
  }
}
```

冷的 demo 查询会返回 HTTP `202`、`status: pending` 和一个 `poll_after_ms` 提示。等那段时间后再发送一次同样的域名。demo 端点没有 poll token。

demo 端点有自己的限制，与上面的认证限制分开：

| 限制 | 值 | 错误码 |
| - | - | - |
| 每个 IP 每小时的总请求数 | 10 | `DEMO_RATE_LIMITED` |
| 每个 IP 每小时的新域名查询数 | 3 | `DEMO_COLD_RATE_LIMITED` |
| 所有调用方每天的新域名查询数 | 共用的每日额度 | `DEMO_BUDGET_EXHAUSTED` |

每一项都会返回 HTTP `429` 和 `Retry-After` header。

## 错误

错误使用标准的 API 封包：

```json theme={null}
{
  "success": false,
  "error": {
    "code": "BRAND_RATE_LIMITED",
    "message": "brand rate limit exceeded",
    "retryable": false,
    "retry_after": 30
  }
}
```

`retry_after` 只在速率限制错误时出现，单位秒。其他错误都没有这个字段。

| 代码 | HTTP | 含义 |
| - | - | - |
| `UNAUTHORIZED` | 401 | API key 缺少、无效或已过期。 |
| `RATE_LIMITED` | 429 | 超过每个 key 的标准速率限制。 |
| `BRAND_RATE_LIMITED` | 429 | 超过 brand 专用的 workspace 限制。 |
| `BRAND_INVALID_REQUEST` | 400 | 请求内容格式错误，或同时发送了 `domain` 和 `email`，或两者都没发送。 |
| `BRAND_FORCE_REFRESH_FORBIDDEN` | 403 | 请求把 `force_refresh` 设为 `true`。目前不提供。 |
| `DOMAIN_IS_MAILBOX_PROVIDER` | 422 | 这个域名属于个人邮箱服务（例如 `gmail.com`），不是公司。请改用公司域名。 |
| `INSUFFICIENT_CREDITS` | 402 | workspace 的 credits 不足。 |
| `BRAND_DISABLED` | 503 | 品牌查询暂时不可用。 |
| `BRAND_UNAVAILABLE` | 503 | poll token 背后的结果暂时无法获取。 |
| `CREDIT_UNAVAILABLE` | 503 | 计费暂时不可用。请重试。 |
| `BRAND_INVALID_POLL_TOKEN` | 400 | poll token 缺少、格式错误或已过期。请重新查询。 |
| `BRAND_NOT_READY` | 404 | 请求的 logo 素材不存在。 |
| `DEMO_RATE_LIMITED`、`DEMO_COLD_RATE_LIMITED`、`DEMO_BUDGET_EXHAUSTED` | 429 | 超过 demo 端点的限制。见上方“匿名 brand demo”。 |

`5xx` 响应（例如 `BRAND_RESPONSE_INVALID`）表示 Hermai 这边失败了。请重试。

## 认证

使用与其他所有 Hermai API 路由相同的 Bearer token。见 [API keys](/zh-Hans/concepts/api-keys)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.