---
title: "快速入门（API）"
description: "通过 REST API 使用 AI 语音智能体接听您的第一通电话：获取 API 密钥、创建智能体、配置电话号码并发起实时测试通话。"
---
本指南将带您完成接听首个 AI 智能体电话所需的四个 REST 调用。
您需要一个 [ThunderPhone 账户](https://app.thunderphone.com)。
注册免费且不到一分钟。更喜欢点击而非使用 curl？
[控制台快速入门](/zh/quickstart-dashboard)无需编写任何代码，
即可完成相同的首个电话。
## 第 1 步：获取 API 密钥
打开 [app.thunderphone.com](https://app.thunderphone.com)。
在控制台中前往 **组织 → 密钥**。
点击 **创建密钥**，为其命名，然后复制
`sk_live_...` 值。原始密钥**仅显示一次**——请立即将其存储到您的密钥管理器中。
遇到问题？[创建服务器 API 密钥](/zh/guides/api-keys)会逐步详细说明
此流程，应用内副驾还可为您实时高亮显示每个控件。
在本指南中，请将 `sk_live_YOUR_API_KEY` 替换为您刚刚复制的值。
该密钥会自动识别您的组织，因此您无需在 URL 中填写组织 ID。
## 第 2 步：创建智能体
智能体定义 AI 如何处理对话——包括提示词、语音、
产品层级、工具和小组件资格。
```bash cURL
curl -X POST https://api.thunderphone.com/v1/agents \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Support",
"prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
"voice": "john",
"product": "spark"
}'
```
```python Python
import os, requests
agent = requests.post(
"https://api.thunderphone.com/v1/agents",
headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
json={
"name": "Customer Support",
"prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
"voice": "john",
"product": "spark",
},
).json()
print("Agent id:", agent["id"])
```
```javascript Node.js
const agent = await fetch("https://api.thunderphone.com/v1/agents", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Customer Support",
prompt: "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
voice: "john",
product: "spark",
}),
}).then((r) => r.json());
console.log("Agent id:", agent.id);
```
产品层级：`spark` 针对成本进行了优化，`bolt` 针对速度进行了优化，
`storm-base` / `storm-extra` 则面向复杂提示词的智能处理进行了优化。请参阅
[智能体](/api-reference/agents#product-tiers-at-a-glance)了解完整
对比。
## 第 3 步：配置电话号码
此调用会向 ThunderPhone 请求一个号码，并将您的新智能体指定为呼入处理程序。（若要从 VoIP
提供商迁移您自己的号码，请参阅[VoIP 连接](/api-reference/voip-connections)。）
```bash cURL
# First provision
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"area_code": "415"}'
# Then assign the agent you created in Step 2
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/ \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inbound_agent_id": 12}'
```
```python Python
number = requests.post(
"https://api.thunderphone.com/v1/phone-numbers",
headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
json={"area_code": "415"},
).json()
requests.patch(
f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
json={"inbound_agent_id": agent["id"]},
)
print("Your ThunderPhone number:", number["number"])
```
您的新号码初始状态为 `status="provisioning"`，并会在几秒内变为
`active`；您关闭浏览器时，该号码便已准备好接听电话。
## 第 4 步（可选）：设置 Webhook
如需接收实时事件（动态通话路由、通话后处理），请添加一个 Webhook 端点。仅订阅您需要的事件。
```bash
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Prod webhook",
"url": "https://your-server.com/thunderphone-webhook",
"events": ["telephony.incoming", "telephony.complete"]
}'
```
响应中包含一次性 `secret`——请将其复制到您的密钥管理器中。使用该密钥验证传入请求中的 `X-ThunderPhone-Signature-V2`
标头（请参阅[Webhook 概述](/zh/webhooks/overview)）。
## 第 5 步：测试您的智能体
拨打您刚刚配置的号码。智能体会接听电话、自我介绍，并遵循您的提示词。
在通话结束后检查通话记录：
```bash
curl https://api.thunderphone.com/v1/calls \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
查看特定通话以获取转录文本和录音 URL：
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
---
## 后续步骤
让您的智能体在对话期间调用您的 API。
从您自己的代码中触发通话。
实时响应通话事件。
记录了每个公开端点。