# 快速开始

> Index of the TerraLab docs for agents: [llms.txt](https://terra-lab.ai/docs/llms.txt). Every docs page is also served as markdown: add .md to its URL.

有两条路径：在代码中调用 REST API，或者把 MCP 服务器添加到 AI 智能体。两者使用同一个账户，共享每月相同的 100 次免费调用。

## 在代码中调用 API

### 创建 API 密钥

1. 在 [terra-lab.ai/login](https://terra-lab.ai/zh-CN/login) 登录。账户免费，不需要银行卡。
2. 打开 [Dashboard, MCP](https://terra-lab.ai/zh-CN/dashboard/mcp)，然后选择 **Advanced**，再选择 **API keys**。
3. 给密钥命名，接受 API 条款，然后点击 **Create key**。
4. 现在就复制密钥：它以 `tlk_` 开头，只显示一次。

把它放在环境变量中，不要写进代码：

```bash
export TERRALAB_API_KEY="tlk_your_key_here"
```

### 检查密钥

`GET /v1/me` 会返回你的账户信息和本月剩余的调用次数。

```bash
curl https://mcp.terra-lab.ai/v1/me \
  -H "Authorization: Bearer $TERRALAB_API_KEY"
```

返回 `401` 表示密钥缺失、拼写错误或已被撤销。

### 发起第一次工具调用

用 `find_places` 查找一个地址的坐标：

```bash
curl -X POST https://mcp.terra-lab.ai/v1/tools/find_places \
  -H "Authorization: Bearer $TERRALAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"12 rue de la Paix, Annecy"}'
```

```python
import os
import requests

response = requests.post(
    "https://mcp.terra-lab.ai/v1/tools/find_places",
    headers={"Authorization": f"Bearer {os.environ['TERRALAB_API_KEY']}"},
    json={"query": "12 rue de la Paix, Annecy"},
    timeout=120,
)
response.raise_for_status()
print(response.json()["structuredContent"])
```

```javascript
const response = await fetch('https://mcp.terra-lab.ai/v1/tools/find_places', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TERRALAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: '12 rue de la Paix, Annecy' }),
});
const data = await response.json();
console.log(data.structuredContent);
```

返回的是一个 JSON 对象：`structuredContent` 包含结果及其 `sources`，`content` 是同一结果的文本形式，`isError` 表示工具是否拒绝了该请求。

### 继续探索

- 用 [extract_open_data](https://terra-lab.ai/docs/api/extract_open_data) 提取某个区域的建筑和道路。
- 用 [get_elevation](https://terra-lab.ai/docs/api/get_elevation) 获取高程、剖面或等高线。
- 在 [API 参考](https://terra-lab.ai/docs/api)中浏览全部 29 个工具。

## 把 TerraLab 添加到 AI 智能体

在 Claude Code 中，一条命令即可：

```bash
claude mcp add --transport http terralab https://mcp.terra-lab.ai/mcp
```

然后在 Claude Code 中运行 `/mcp` 并登录 TerraLab。Claude、ChatGPT、Cursor、Codex 和 VS Code 的方法见 [MCP 服务器](https://terra-lab.ai/zh-CN/docs/mcp)。

例如可以这样问：“显示里昂 Part-Dieu 车站周围 500 m 内的建筑，并给我一个 GeoPackage。”

Source: https://terra-lab.ai/zh-CN/docs/quickstart · Updated 2026-10-27