SMS Relay - API 文档

基本信息

所有接口同时支持 GET 和 POST 方法。

Base URL: https://sms.oapi.vip/api.php?action=<endpoint>

GET 方式：参数通过 URL query string 传递，如 /api.php?action=open_get_sms&api_key=KEY&code=CDK
POST 方式：参数通过 JSON body 传递，API Key 通过 Header 或 query 传递。
关于 remaining 字段：返回 CDK 剩余可用次数。值为 -1 表示无限次使用。

接口鉴权

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

方式一 — HTTP Header（POST 推荐）

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

方式二 — Query 参数（GET/POST 通用）

GET /api.php?action=open_get_phone&api_key=sk-your-api-key-here&code=CDK_CODE

GET 方式直接在 URL 中带上 api_key 和业务参数即可，无需设置 Header，集成更简单。

频率限制与风控

API 采用三层防护机制，正常使用不会触发限制。

层级	限制对象	阈值	超限封锁	说明
第一层	同一 IP（所有请求）	180 次/分钟	5 分钟	防 DDoS 和脚本扫描
第二层	同一 IP（无效 key）	10 次/分钟	15 分钟	防爆破 CDK
第三层	单个有效 key	60 次/分钟	2 分钟	防单 key 滥用

正常使用参考：每 5 秒轮询一次 open_get_sms = 12 次/分钟，远低于限制。即使 2 秒轮询一次（30 次/分钟）也不会触发。多个 CDK 并发时注意 IP 总量不超过 180 次/分钟即可。

超限响应

触发频率限制时，接口返回 HTTP 429 Too Many Requests，响应头包含 Retry-After（秒数）：

{
  "ok": false,
  "error": "该 API Key 调用过于频繁，已被封锁 2 分钟",
  "retry_after": 120
}

最佳实践

轮询间隔建议 ≥ 3 秒，避免不必要的请求浪费
收到 HTTP 429 后，根据 retry_after 暂停后再重试
验证码已收到时立即停止轮询，不要继续调用
保管好 API Key，泄露后立即在后台禁用并重新生成

1. 获取手机号

GET/POST /api.php?action=open_get_phone

通过 CDK 兑换码获取一个可用手机号。如果该 CDK 已绑定号码，返回相同号码。

GET 请求示例

GET /api.php?action=open_get_phone&api_key=sk-xxx&code=SMS-A3DX-HRQF-ZC4Y

POST 请求参数

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

成功响应 (200)

{
  "ok": true,
  "phone": "+18032579874",
  "remaining": 2,
  "allow_change": 1
}

字段	类型	说明
`ok`	boolean	是否成功
`phone`	string	分配的手机号 (E.164 格式，如 +1xxx)
`remaining`	number	CDK 剩余可用次数，-1 表示无限
`allow_change`	number	该项目是否允许换号：`1`=允许，`0`=不支持换号（调用 open_change_phone 会返回 403）

一个 CDK 绑定一个手机号后，该号码专属于此 CDK 使用，不会被其他 CDK 获取。

2. 获取验证码

GET/POST /api.php?action=open_get_sms

查询已绑定手机号收到的验证码。如未收到短信返回 ok:false，调用方应每 3 秒轮询。

GET 请求示例

GET /api.php?action=open_get_sms&api_key=sk-xxx&code=SMS-A3DX-HRQF-ZC4Y

POST 请求参数

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

成功响应 — 收到验证码 (200)

{
  "ok": true,
  "sms": "您的 OpenAI 验证代码是：874895",
  "code": "874895",
  "remaining": 1
}

等待中响应 — 未收到 (200)

{
  "ok": false,
  "error": "No new SMS received yet"
}

字段	类型	说明
`ok`	boolean	true=收到验证码，false=暂未收到
`sms`	string	完整短信内容
`code`	string	提取的验证码数字
`remaining`	number	CDK 剩余可用次数，-1 表示无限

重要：验证码获取成功后自动消耗 1 次使用次数。
号码使用模式：
• 一卡一码模式：号码绑定当前 CDK，同一 CDK 可继续使用此号码接收下一个验证码。
• 多轮使用模式：号码接码后释放，可被其他 CDK 使用。系统会自动过滤该号码最近 3 小时内已接收过的验证码，确保每个 CDK 只获取到新验证码。

3. 更换手机号

GET/POST /api.php?action=open_change_phone

释放当前绑定的号码并重新分配一个新号码。用于号码无法收到验证码时更换。

GET 请求示例

GET /api.php?action=open_change_phone&api_key=sk-xxx&code=SMS-A3DX-HRQF-ZC4Y

POST 请求参数

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

成功响应 (200)

{
  "ok": true,
  "phone": "+19876543210",
  "remaining": 2
}

字段	类型	说明
`ok`	boolean	是否成功
`phone`	string	新分配的手机号
`remaining`	number	CDK 剩余可用次数，-1 表示无限

限制条件：如果当前号码已成功接收过验证码，则不允许换号，会返回 400 错误。只有从未收到过验证码的号码才能更换。

项目换号开关：若该 CDK 所属项目关闭了换号功能，调用本接口会返回 403，响应为 {"ok": false, "error": "This project does not support changing numbers", "no_change": true}。可先看 open_get_phone 返回的 allow_change 字段判断。

完整对接流程

Python 示例

import requests
import time

BASE_URL = "https://sms.oapi.vip/api.php"
API_KEY = "sk-your-api-key"
CDK_CODE = "SMS-A3DX-HRQF-ZC4Y"

headers = {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY
}

# 第一步：获取手机号
resp = requests.post(
    f"{BASE_URL}?action=open_get_phone",
    json={"code": CDK_CODE},
    headers=headers
)
data = resp.json()
if not data["ok"]:
    print(f"获取号码失败: {data['error']}")
    exit()
phone = data["phone"]
print(f"获取到号码: {phone}")

# 第二步：轮询获取验证码（建议最多等待 120 秒）
print("等待验证码...")
for i in range(40):  # 最多轮询 40 次 (约 120 秒)
    time.sleep(3)
    resp = requests.post(
        f"{BASE_URL}?action=open_get_sms",
        json={"code": CDK_CODE},
        headers=headers
    )
    data = resp.json()
    if data["ok"]:
        print(f"收到验证码: {data['code']}")
        print(f"短信全文: {data['sms']}")
        print(f"剩余次数: {data['remaining']}")
        break
else:
    print("超时未收到验证码，尝试换号...")
    # 第三步（可选）：换号
    resp = requests.post(
        f"{BASE_URL}?action=open_change_phone",
        json={"code": CDK_CODE},
        headers=headers
    )
    data = resp.json()
    if data["ok"]:
        print(f"换号成功，新号码: {data['phone']}")
    else:
        print(f"换号失败: {data['error']}")

cURL 示例 — GET 方式（推荐，最简单）

# 获取手机号
curl "https://sms.oapi.vip/api.php?action=open_get_phone&api_key=sk-your-api-key&code=SMS-A3DX-HRQF-ZC4Y"

# 获取验证码（轮询）
curl "https://sms.oapi.vip/api.php?action=open_get_sms&api_key=sk-your-api-key&code=SMS-A3DX-HRQF-ZC4Y"

# 更换手机号
curl "https://sms.oapi.vip/api.php?action=open_change_phone&api_key=sk-your-api-key&code=SMS-A3DX-HRQF-ZC4Y"

cURL 示例 — POST 方式

# 获取手机号
curl -X POST "https://sms.oapi.vip/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://sms.oapi.vip/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://sms.oapi.vip/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"}'

错误码说明

HTTP 状态码	说明
200	请求成功（`"ok": true`）或正常轮询等待（`"ok": false`+错误提示）
400	参数错误、CDK 不可用、已接过码不允许换号、暂无可用号码
403	API Key 无效或已禁用
409	无活跃会话，需先调用 open_get_phone
429	触发频率限制（三层防护），响应中含 `retry_after` 秒数
502	上游短信 API 配置错误

错误响应格式

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

常见错误信息

error	说明	处理建议
Missing code parameter	未传 code 参数	检查请求体
无效的CDK兑换码	CDK 不存在	检查 code 是否正确
CDK已使用完毕	已达到最大使用次数	使用新的 CDK
CDK已过期	超过有效期	使用新的 CDK
No available phone numbers	当前项目无可用号码	稍后重试或联系管理员
No new SMS received yet	轮询中，暂未收到	继续轮询
Phone already received SMS, cannot change	已收到验证码，不能换号	号码正常工作，无需换号
This phone has already received SMS successfully, cannot change	号码历史已接过码	号码正常，不允许换号

SMS Relay API 文档

基本信息

接口鉴权

方式一 — HTTP Header（POST 推荐）

方式二 — Query 参数（GET/POST 通用）

频率限制与风控

超限响应

最佳实践

1. 获取手机号

GET 请求示例

POST 请求参数

成功响应 (200)

2. 获取验证码

GET 请求示例

POST 请求参数

成功响应 — 收到验证码 (200)

等待中响应 — 未收到 (200)

3. 更换手机号

GET 请求示例

POST 请求参数

成功响应 (200)

完整对接流程

Python 示例

cURL 示例 — GET 方式（推荐，最简单）

cURL 示例 — POST 方式

错误码说明

错误响应格式

常见错误信息