API接口文档 – 龙虾PRO

1. 快速开始

申请 API 账号
登录后打开 API 服务，填写申请说明并提交。审核通过后系统签发 API Key。
保存 Key
Key 形如 lxk_xxxxxxxx…。请妥善保管，不要提交到公开仓库或前端静态页面。

发起第一次调用

以 IP 归属地查询为例（GET）：

bash

curl -sS -X GET \
  'https://www.longxiapro.com/index.php/lx-api/v1/ip?ip=114.114.114.114' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

检查返回
成功时 HTTP 状态一般为 200，JSON 中 status 为 success，业务数据在 data 字段；失败时 status 为 error，见错误码章节。

2. 鉴权说明

每个请求必须携带 API Key，仅支持官方 Header 方式：

Authorization: Bearer

http

Authorization: Bearer lxk_your_key_here

Key 与账号一一绑定；重新签发后旧 Key 立即失效。
账号被停用 / 拉黑 / 拒绝后，所有调用将返回鉴权失败。
请勿在浏览器公开页面硬编码 Key；服务端代理调用更安全。
不支持自定义头（如 X-LX-API-Key）或 Query 传 Key，请按上述官方方式调用。

3. 配额与计费

每日免费次数：按「服务编码」独立统计，跨日重置。
积分兑换：免费次数用尽后，可按服务配置的「积分兑换次数」消耗兑换余额。
限流：触发时返回 429 类错误，请退避重试。

4. 统一响应与错误码

成功响应结构（示意）

json

{
  "status": "success",
  "message": "ok",
  "data": { /* 业务字段 */ }
}

失败响应结构（示意）

json

{
  "status": "error",
  "code": "invalid_key",
  "message": "无效的 API Key",
  "data": null
}

场景	HTTP	code 示例	说明
缺少 Key	401	missing_key	未传 Authorization: Bearer
Key 无效	401	invalid_key	Key 错误或已轮换
账号停用	403	key_disabled / account_*	停用、吊销、拉黑等
参数错误	400	bad_*	如 bad_ip、bad_phone、bad_image
配额不足	402/403	quota_*	免费与兑换均不可用
限流	429	rate_limit	请稍后重试
服务不可用	503	unavailable	模块未加载或维护中

5. 图像识别 OCR

统一入口 POST /ocr，通过 mode 指定识别类型。计费服务编码为 ocr_{mode}（如身份证 ocr_id_card）。

Endpointhttps://www.longxiapro.com/index.php/lx-api/v1/ocr

MethodPOST

编码ocr_{mode}

Contentmultipart/form-data 或 application/json

请求参数

参数	位置	必填	说明
`image`	multipart	二选一	图片文件字段
`image_b64`	JSON body	二选一	Base64 图片（可带 data:image/… 前缀）
`mode`	form/json	建议	识别模式，默认 general。常用：id_card / invoice / bank_card / driving_license 等
`lang`	form/json	否	语言，默认 auto
`preprocess`	form/json	否	1/0 是否预处理，默认 1

请求示例

cURL · multipart 上传身份证

bash

curl -sS -X POST 'https://www.longxiapro.com/index.php/lx-api/v1/ocr' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'image=@./id_card.jpg' \
  -F 'mode=id_card' \
  -F 'preprocess=1'

JSON · Base64

bash

curl -sS -X POST 'https://www.longxiapro.com/index.php/lx-api/v1/ocr' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image_b64": "/9j/4AAQSkZJRg...",
    "mode": "invoice",
    "lang": "auto"
  }'

Python · requests

python

import requests
url = 'https://www.longxiapro.com/index.php/lx-api/v1/ocr'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}
files = {'image': open('id_card.jpg', 'rb')}
data = {'mode': 'id_card', 'preprocess': '1'}
r = requests.post(url, headers=headers, files=files, data=data, timeout=60)
print(r.status_code, r.json())

成功返回示例

json

{
  "status": "success",
  "message": "ok",
  "data": {
    "mode": "id_card",
    "text": "姓名 张三\n公民身份号码 1101…",
    "fields": {
      "name": "张三",
      "id_number": "110101199001011234",
      "address": "北京市…"
    },
    "engine": "…"
  }
}

支持模式示例：general（通用文字）、iocr_general（iOCR通用版）、chinese_en（中英混合）、english（纯英文）、handwriting（手写文字）、table（表格/多列）、numbers（纯数字）、amount_money（金额专识）、date_time（日期时间）、contact（联系方式）、id_card（身份证识别）、driving_license（驾驶证识别） … 等
图片建议 ≤ 10MB；过暗、模糊、倾斜会影响字段提取。
返回字段结构可能因 mode 与引擎版本略有差异，请以 fields / text 为准做兼容解析。

6. IP 归属地查询 ip

查询 IPv4/IPv6 的省市区、运营商，并附带当地天气概况（若有经纬度）。

Endpointhttps://www.longxiapro.com/index.php/lx-api/v1/ip

MethodGET / POST

编码ip

请求参数

参数	位置	必填	说明
`ip`	query/body	否	目标 IP；为空则取客户端 IP

请求示例

GET

bash

curl -sS 'https://www.longxiapro.com/index.php/lx-api/v1/ip?ip=8.8.8.8' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST JSON

bash

curl -sS -X POST 'https://www.longxiapro.com/index.php/lx-api/v1/ip' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"ip":"114.114.114.114"}'

成功返回示例

json

{
  "status": "success",
  "message": "ok",
  "data": {
    "ip": "114.114.114.114",
    "geo": {
      "country": "中国",
      "province": "江苏省",
      "city": "南京市",
      "isp": "…",
      "lat": 32.06,
      "lon": 118.80
    },
    "weather": {
      "temp": 26,
      "humidity": 68,
      "text": "多云"
    }
  }
}

非法 IP 返回 bad_ip。

7. 手机号归属地 phone

查询 11 位中国大陆手机号的号段归属：省 / 市 / 运营商 / 区号等。

Endpointhttps://www.longxiapro.com/index.php/lx-api/v1/phone

MethodGET / POST

编码phone

请求参数

参数	位置	必填	说明
`phone`	query/body	是	11 位手机号，允许含空格或横线（服务端会清洗）

请求示例

GET

bash

curl -sS 'https://www.longxiapro.com/index.php/lx-api/v1/phone?phone=13800138000' \
  -H 'Authorization: Bearer YOUR_API_KEY'

成功返回示例

json

{
  "status": "success",
  "message": "ok",
  "data": {
    "phone": "13800138000",
    "province": "北京",
    "city": "北京",
    "isp": "中国移动",
    "area_code": "010",
    "zip": "100000"
  }
}

非 1 开头 11 位号返回 bad_phone。

8. 手机号空号检测 phone_empty

检测手机号是否空号 / 无效 / 风险号 / 沉默号。核心由 Python 引擎完成：本地规则 + 在线号段辅助 + 可选商业 HLR Provider。

Endpointhttps://www.longxiapro.com/index.php/lx-api/v1/phone-empty

MethodGET / POST

编码phone_empty

请求参数

参数	位置	必填	说明
`phone`	query/body	单号必填	手机号，支持 +86 / 空格横线
`phones`	query/body	批量	数组或逗号分隔，最多 50 个
`deep`	query/body	否	1/0 是否在线号段深探测，默认 1

请求示例

GET 单号

bash

curl -sS 'https://www.longxiapro.com/index.php/lx-api/v1/phone-empty?phone=13800138000' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST 批量

bash

curl -sS -X POST 'https://www.longxiapro.com/index.php/lx-api/v1/phone-empty' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"phones":["13800138000","12345678901"],"deep":1}'

Python

python

import requests
r = requests.get(
  'https://www.longxiapro.com/index.php/lx-api/v1/phone-empty',
  params={'phone': '13800138000'},
  headers={'Authorization': 'Bearer YOUR_API_KEY'},
  timeout=20,
)
print(r.json())

成功返回示例

json

{
  "status": "success",
  "message": "ok",
  "data": {
    "phone": "12345678901",
    "phone_mask": "123****8901",
    "status": "empty",
    "status_label": "空号",
    "is_empty": true,
    "confidence": 0.9,
    "carrier": "",
    "reasons": ["连号或全相同数字…"],
    "advice": "检测为空号…",
    "engine": "phone_empty",
    "version": "1.0.0"
  }
}

状态枚举：empty / normal / invalid / risk / silence / unknown。
无商业 Provider 时，引擎可识别明显空号/无效号；运营商级「在网确认」请在后台配置 HLR 接口。
批量返回 results[] 与 summary 统计。

9. 24 小时天气预报 weather

支持城市名、城市代码、IP、经纬度等多种查询模式，返回逐小时预报与生活指数。

Endpointhttps://www.longxiapro.com/index.php/lx-api/v1/weather

MethodGET / POST

编码weather

请求参数

参数	位置	必填	说明
`mode`	query/body	否	city \| code \| ip \| geo，默认 city
`q`	query/body	是	查询值：北京 / 101010100 / IP / lat,lon
`lat,lon`	query/body	条件	geo 模式可用独立 lat、lon 参数

请求示例

城市名

bash

curl -sS 'https://www.longxiapro.com/index.php/lx-api/v1/weather?mode=city&q=北京' \
  -H 'Authorization: Bearer YOUR_API_KEY'

经纬度

bash

curl -sS 'https://www.longxiapro.com/index.php/lx-api/v1/weather?mode=geo&q=39.9,116.4' \
  -H 'Authorization: Bearer YOUR_API_KEY'

成功返回示例

json

{
  "status": "success",
  "message": "ok",
  "data": {
    "city": "北京",
    "hours": [
      { "time": "14:00", "temp": 31, "text": "晴", "pop": 10 },
      { "time": "15:00", "temp": 32, "text": "晴", "pop": 10 }
    ],
    "aqi": { "value": 65, "level": "良" },
    "tips": ["紫外线强，注意防晒"]
  }
}

字段名可能随数据源微调，请做防御性解析。

FAQ 常见问题

Q：为什么返回 401 invalid_key？

检查 Header 是否为 Authorization: Bearer YOUR_KEY、Key 是否含多余空格/换行、是否已重新签发导致旧 Key 失效。

Q：OCR 应该传哪个服务编码？

计费按 ocr_{mode}。例如身份证识别 mode=id_card，对应服务编码 ocr_id_card。账号需开通对应子服务（或管理员开通全部 OCR 子模式）。

Q：免费次数什么时候重置？

按自然日重置。未用完的当日免费次数不累计到次日。

Q：如何排查网络与跨域？

浏览器直连可能受 CORS 限制，建议后端代理转发。可先用 curl 验证 Key 与参数是否正确。

需要 Key？前往 API 服务申请页。