使用测试模式安全构建

测试模式 API 密钥 (ody_test_…) 的行为与实时密钥完全相同，但任何会花费金钱或触及外部世界的操作都会被模拟——消息发送、号码购买、出站 AI 呼叫、代理发布和 10DLC 注册（以模拟模式运行）——这使得它们非常适合开发和 CI。

开始之前

• 您必须是工作区的管理员或所有者才能创建密钥。
• 了解测试模式的作用和不隔离的内容：测试密钥针对您的真实工作区数据运行。联系人创建、更新和删除是真实的，对话状态更改是真实的，代理草稿保存 (PATCH /v1/api/agent) 也是真实的。模拟的是花费：发送、号码购买、出站 AI 呼叫、代理发布和 10DLC 备案。

分步指南

1. 点击侧边栏中的设置，然后点击开发者 API。

2. 照常填写创建表单——名称和范围（请参阅获取您的 Ody API 密钥）。

3. 在密钥类型下，选择测试。提示确认：测试密钥读取真实数据，但从不发送真实短信——发送被记录为模拟。

4. 点击创建密钥并从一次性横幅中复制 ody_test_… 密钥。

5. 像使用实时密钥一样使用它——相同的基本 URL、端点、范围和速率限制：

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_test_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"+15125550123","body":"CI smoke test"}'

响应是正常的 201，其中包含 "simulated": true，并且消息在线程中显示 deliveryStatus: "simulated"。

哪些是相同的，哪些是模拟的

行为	使用 ody_test_… 密钥
读取联系人、对话、呼叫、号码	真实数据，与实时相同
创建/更新/删除联系人	真实——更改您的工作区
设置对话状态	真实
POST /v1/api/messages / MCP send_message	模拟——已记录，从不传输
POST /v1/api/numbers / MCP buy_number	模拟——"simulated": true，未订购、未配置、未收费
POST /v1/api/calls / MCP place_call	模拟——一个 sim_… 呼叫 ID，未拨号，未消耗积分
POST /v1/api/agent/publish	模拟——您的配置保持草稿状态，不会上线
PATCH /v1/api/agent（草稿保存）	真实——与实时相同
POST /v1/api/messaging/registration	模拟模式——完整的 10DLC 流程运行，但没有提交到注册表，也没有费用
范围、速率限制、错误、分页、幂等性	与实时相同
Webhook 端点管理	真实端点，与实时相同

在密钥列表中，测试密钥会显示测试徽章和 ody_test_…WXYZ 提示，这样您就不会将它们与实时密钥混淆。

在 CI 中使用测试模式

• 为每个管道（例如“GitHub Actions”）创建一个专用的测试密钥，这样您就可以独立撤销它，并且“上次使用”列保持有意义。
• 将其存储为 CI 密钥（例如 ODY_API_KEY）——您的代码在不同环境之间不会改变，只有密钥会改变。
• 在发送响应中断言 simulated: true，以捕获在 CI 中意外配置的实时密钥。
• 请记住，联系人写入是真实的：将 CI 指向专用工作区，或清理您的测试创建的联系人。

相关文章

• 获取您的 Ody API 密钥
• API 概述和身份验证
• 使用 MCP 连接 AI 工具
• SDK 快速入门：TypeScript 和 Python