跳转到内容
Zelnum API

cURL / SDK 示例

所有示例都用同一个公开基础地址：

https://api.zelnum.com/api/v1

把 YOUR_KEY_HERE 换成认证里创建的 Key；产品 slug 请到批量产品列表取。

提交号码数组

Section titled “提交号码数组”
Terminal window
curl -X POST "https://api.zelnum.com/api/v1/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
        "product": "YOUR_PRODUCT_SLUG",
        "country": "CN",
        "phones": ["+8613800138000", "+8613800138001"]
      }'

响应会给你任务令牌和已预扣的金额：

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "summary": { "total": 5000, "cost_deducted": 0.500000 }
}

上传文件

Section titled “上传文件”
Terminal window
curl -X POST "https://api.zelnum.com/api/v1/detect/file" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -F "product=YOUR_PRODUCT_SLUG" \
  -F "country=CN" \
  -F "file=@numbers.txt"

numbers.txt 每行一个号码，最大 50 MB。注意这里用的是 -F 而不是 -d：该端点接收 multipart/form-data。

轮询到结束

Section titled “轮询到结束”
Terminal window
TOKEN=xKj9aP3qLm7v


while true; do
  status=$(curl -s "https://api.zelnum.com/api/v1/tasks/$TOKEN" \
    -H "X-API-Key: YOUR_KEY_HERE")


  printf '%s\n' "$status" | jq '{status, progress, valid, invalid, unknown}'


  case "$(printf '%s' "$status" | jq -r .status)" in
    completed|failed) break ;;
  esac


  sleep 4
done

不论任务多大，4 秒一次的间隔都是合理的；任务页用 progress 报告百分比。

下载结果

Section titled “下载结果”
Terminal window
curl -s "https://api.zelnum.com/api/v1/tasks/$TOKEN/result" \
  -H "X-API-Key: YOUR_KEY_HERE" | jq -r .download_url

download_url 是有时效的——必须在 expires_at 之前取走，否则文件就没了。然后：

Terminal window
curl -L -H "X-API-Key: YOUR_KEY_HERE" \
  "https://api.zelnum.com/api/v1/tasks/$TOKEN/download" -o results.csv

一个脚本跑完全流程

Section titled “一个脚本跑完全流程”
#!/usr/bin/env bash
set -euo pipefail


API="https://api.zelnum.com/api/v1"
KEY="YOUR_KEY_HERE"
SLUG="YOUR_PRODUCT_SLUG"


task=$(curl -s -X POST "$API/detect" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d "{\"product\":\"$SLUG\",\"country\":\"CN\",\"phones\":[\"+8613800138000\"]}" \
  | jq -r .task_id)


echo "task $task submitted"


until [ "$(curl -s "$API/tasks/$task" -H "X-API-Key: $KEY" | jq -r .status)" = "completed" ]; do
  sleep 4
done


url=$(curl -s "$API/tasks/$task/result" -H "X-API-Key: $KEY" | jq -r .download_url)
curl -L "$url" -o results.csv


echo "wrote results.csv"

接下来

Section titled “接下来”