API 文档

🔑 认证

每个请求都要带上你的 Key。无效或停用的 Key 返回 401。

X-API-Key: fk_你的key

认证失败示例

HTTP 401
{"detail": "Invalid or inactive API key"}

💰 查询余额

GET /api/v1/balance

curl "https://你的域名/api/v1/balance" -H "X-API-Key: 你的KEY"

返回

{"success": true, "balance": 9.9500, "price": 0.001}

balance=账户余额(美元)，price=每个粉丝单价。余额不足时上传会被拒绝。

⬆️ 上传数据（下单）

POST /api/v1/upload

字段	说明
data	Instagram 链接文本，可多个拼接。只接受 instagram.com 链接。
quantity	每个目标要关注的数量(粉丝数)。默认 1。

费用 = 目标数 × quantity × 单价，上传时从余额扣除；做不满会退未完成部分。

curl -X POST "https://你的域名/api/v1/upload" \
  -H "X-API-Key: 你的KEY" -H "Content-Type: application/json" \
  -d '{"data": "https://www.instagram.com/kinlock", "quantity": 100}'

📋 返回示例

✅ 成功

合法目标入库，扣费并返回订单与余额。

{
  "success": true,
  "message": "成功 1 条，失败 0 条",
  "accepted_count": 1,
  "rejected_count": 0,
  "quantity_per_target": 100,
  "unit_price": 0.001,
  "charged": 0.1000,          // 本次扣费
  "balance": 9.9000,          // 扣费后余额
  "orders": [
    {"id": "57e34a3a3e1d478a", "username": "kinlock", "quantity": 100, "status": "pending"}
  ],
  "rejected": []
}

⚠️ 部分成功（有非法数据）

合法的进 orders，非法的进 rejected（原样回显+原因），只对合法的扣费。

{
  "success": true,
  "message": "成功 1 条，失败 1 条",
  "accepted_count": 1,
  "rejected_count": 1,
  "orders": [ {"id":"6f83...", "username":"kinlock", "quantity":100, "status":"pending"} ],
  "rejected": [
    {"raw": "https://tiktok.com/bad", "reason": "not an instagram.com link / 非 instagram 链接"}
  ]
}

❌ 全部失败（无合法链接）

{
  "success": false,
  "message": "成功 0 条，失败 1 条",
  "accepted_count": 0,
  "rejected_count": 1,
  "orders": [],
  "rejected": [ {"raw":"https://youtube.com/abc", "reason":"not an instagram.com link / 非 instagram 链接"} ]
}

💸 余额不足

HTTP 402
{"detail": "余额不足 / insufficient balance: 需 $0.1000 (1目标×100个×$0.001), 余额 $0.0500"}

🔑 Key 无效

HTTP 401
{"detail": "Invalid or inactive API key"}

⏱️ 频率超限

HTTP 429  (Retry-After header)
{"detail": "Too Many Requests：上传超过 5 次/1秒"}

限流：每个 Key 每秒最多 5 次。收到 429 按 Retry-After 秒后重试。

🔍 查询订单状态

GET /api/v1/orders

可选参数：status_filter (pending/processing/completed/failed)、start、end (YYYY-MM-DD)

curl "https://你的域名/api/v1/orders?status_filter=completed&start=2026-07-01" \
  -H "X-API-Key: 你的KEY"

返回

{
  "success": true, "count": 1,
  "orders": [{
    "id":"57e3...", "username":"kinlock", "status":"completed",
    "quantity":100, "done":100, "uid":"25025320",
    "followers_start":"500", "followers_end":"600",
    "created_at":"2026-07-23 10:00:00", "updated_at":"2026-07-23 10:30:00"
  }]
}

status: pending待处理 / processing进行中 / completed已完成 / failed失败(含部分完成退款)。done=已完成数，quantity=需求数。

💻 Python 示例

import requests
BASE = "https://你的域名"
KEY  = "你的KEY"
h = {"X-API-Key": KEY}

# 查余额
print(requests.get(f"{BASE}/api/v1/balance", headers=h).json())

# 下单：关注 kinlock 100 个粉丝
r = requests.post(f"{BASE}/api/v1/upload", headers=h,
    json={"data": "https://www.instagram.com/kinlock", "quantity": 100})
print(r.json())   # 看 charged/balance/orders

# 查状态
print(requests.get(f"{BASE}/api/v1/orders", headers=h,
    params={"status_filter": "completed"}).json())