SMS Relay API 文档

开放接口，供第三方开发者集成使用

接口鉴权 获取手机号 获取验证码 更换手机号 错误码

基本信息

所有接口使用 POST 方法，请求体为 JSON 格式。

Base URL: https://your-domain.com/api.php?action=<endpoint>

接口鉴权

所有开放接口需要提供有效的 API Key 进行身份验证。API Key 在管理后台创建。

推荐方式 — HTTP Header

X-API-Key: sk-your-api-key-here

备选方式 — Query 参数

POST /api.php?action=open_get_phone&api_key=sk-your-api-key-here

推荐使用 Header 方式，更加安全。

1. 获取手机号

POST /api.php?action=open_get_phone
通过 CDK 兑换码获取一个可用手机号。如果该 CDK 已绑定号码，返回相同号码。

请求参数

{
  "code": "SMS-A3DX-HRQF-ZC4Y"
}

成功响应 (200)

{
  "ok": true,
  "phone": "+18032579874",
  "remaining": 2
}
字段说明
ok是否成功
phone分配的手机号 (E.164 格式)
remainingCDK 剩余可用次数

2. 获取验证码

POST /api.php?action=open_get_sms
查询已绑定手机号收到的验证码。如未收到短信返回失败，调用方应每 1-3 秒轮询。

请求参数

{
  "code": "SMS-A3DX-HRQF-ZC4Y"
}

成功响应 (200)

{
  "ok": true,
  "sms": "您的 OpenAI 验证代码是：874895",
  "code": "874895",
  "remaining": 1
}
字段说明
ok是否成功
sms完整短信内容
code提取的验证码
remainingCDK 剩余可用次数

注意：验证码获取成功后，该次使用自动消耗，号码释放回号码池。

3. 更换手机号

POST /api.php?action=open_change_phone
释放当前绑定的号码并重新分配一个新号码。用于客户未收到验证码时更换号码。

请求参数

{
  "code": "SMS-A3DX-HRQF-ZC4Y"
}

成功响应 (200)

{
  "ok": true
}

换号成功后需重新调用 open_get_phone 获取新号码。

错误码说明

HTTP 状态码说明
200请求成功，返回 "ok": true
400参数错误、CDK 不可用、暂无验证码
403API Key 无效或已禁用
409号码状态变更，需重新获取号码
502上游短信 API 暂时不可用

错误响应格式

{
  "ok": false,
  "error": "具体的错误信息描述"
}

调用示例 (cURL)

# 获取手机号
curl -X POST "https://your-domain.com/api.php?action=open_get_phone" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-api-key" \
  -d '{"code": "SMS-A3DX-HRQF-ZC4Y"}'

# 获取验证码 (轮询)
curl -X POST "https://your-domain.com/api.php?action=open_get_sms" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-api-key" \
  -d '{"code": "SMS-A3DX-HRQF-ZC4Y"}'

# 更换手机号
curl -X POST "https://your-domain.com/api.php?action=open_change_phone" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-api-key" \
  -d '{"code": "SMS-A3DX-HRQF-ZC4Y"}'