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

# API 概览

> 使用 API Key 连接，搜索并检查接口，再发起请求并读取结果。

使用一个 Glasser API Key 和工作空间余额，即可在自己的应用中调用专业数据提供商的付费数据。每个**接口**对应数据提供商的一项操作，例如公司信息补全或关键词研究。先搜索数据源，检查接口的输入和价格，再运行接口获取数据。

如需了解数据流程并选择产品的接入方式，请先阅读 [集成指南](https://glasser.ai/docs/zh/integrations/overview.md)。

## 认证

API 服务地址为 `https://api.glasser.ai`。请求 `/v1` 需要 API Key。请在 [API Key 页面](https://app.glasser.ai/keys?locale=zh-CN)创建，并将其设置为环境变量 `GLASSER_API_KEY`。通过 `Authorization: Bearer` 请求头发送。

使用以下免费的余额请求检查连接：

```bash theme={null}
curl --request GET \
  --url https://api.glasser.ai/v1/balance \
  --header "Authorization: Bearer $GLASSER_API_KEY"
```

## 速率限制

当前限制为：**每个 API Key、每条 API 路由，每分钟 600 次请求**。

## 浏览数据提供商与接口

通过 `GET /public/catalog` [列出数据提供商与接口](https://glasser.ai/docs/zh/api-reference/endpoints/list.md)。此公开请求免费，无需 API Key，一次返回完整列表：`providers` 描述各数据提供商，`entries` 列出其接口及展示价格。

开发时可据此选择接口，或构建数据提供商选择器。列表经过缓存，不应用 API Key 的 Policy。选定接口后，使用 API Key 检查其 Schema 和当前价格。

## 搜索、检查、运行

1. \*\*[搜索接口](https://glasser.ai/docs/zh/api-reference/endpoints/search.md)。\*\*查找任务所需的数据。使用 `query` 传入搜索词，例如 `company enrichment`，并提供必填的 `use_case`，例如 `Create a company profile for glasser.ai`。结果包含数据提供商、接口、接口版本及价格。
2. \*\*[检查接口](https://glasser.ai/docs/zh/api-reference/endpoints/inspect.md)。\*\*阅读其 `input_schema`、示例输入，以及包括各类结果计费规则在内的价格信息。按此 Schema 构造数据提供商所需的输入。
3. \*\*[运行接口](https://glasser.ai/docs/zh/api-reference/runs/create.md)。\*\*将所选 `provider` 和 `endpoint` 连同构造好的输入发送到 `POST /v1/runs`。请求会创建 Run，并按该接口的计费规则获取数据。

搜索和检查均免费。创建 Run 必须提供 `Idempotency-Key` 请求头。重试同一个请求时保持其值不变；开始新的执行时，使用新值。

## 读取结果

数据请求返回一个 **Run**。使用结果前，请检查以下字段：

| 字段 | 检查内容 |
| - | - |
| `status` | Run 是否结束。对于 `202` 响应，通过[获取 Run](https://glasser.ai/docs/zh/api-reference/runs/get.md)继续查询。 |
| `provider_response.http_status` | 数据提供商返回的是数据还是错误。`COMPLETED` 也可能包含数据提供商错误。 |
| `provider_response.error` | 数据提供商响应不成功时的错误正文。 |
| `output` | 数据提供商成功响应中的数据。 |
| `charge_usd` | 此 Run 的费用，与状态分别判断。 |
| `run_url` | 在工作空间中打开 Run。 |

即使数据提供商拒绝请求，Run 也可能返回 HTTP `200`，且 `status` 为 `"COMPLETED"`。此时 `output` 为 `null`；请从 `provider_response` 读取数据提供商的状态和错误正文。Run 列表只包含摘要；完整错误详情请通过 [获取 Run](https://glasser.ai/docs/zh/api-reference/runs/get.md)读取。

使用相同 `Idempotency-Key` 和输入重试已完成的 Run，会返回原结果，不会再次调用数据提供商。开始另一次尝试时使用新键，包括修改输入后重新请求的情况。

Run 状态、定价和重试规则见[工作原理](https://glasser.ai/docs/zh/how-it-works.md)。

## 常见任务的 Solutions

Solutions 简化了常见请求的流程。例如， `company_intelligence` 接收域名，由 Glasser 选择接口并转换为数据提供商所需的输入。当 Glasser 提供的参数能够满足任务时，可使用此方式。它使用相同的 API Key 和余额，返回普通 Run。

可用能力、数据提供商选择和费用见 [Solutions 概览](https://glasser.ai/docs/zh/api-reference/solutions/overview.md)。


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