API Documentation

🔑 Authentication

Every request must include your key. Invalid/disabled keys return 401.

X-API-Key: fk_你的key

Auth failure

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

💰 Check Balance

GET /api/v1/balance

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

Response

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

balance = account balance (USD), price = per-follower price. Uploads are rejected when balance is insufficient.

⬆️ Upload (Place Order)

POST /api/v1/upload

Field	Description
data	Instagram links text (multiple ok). Only instagram.com links accepted.
quantity	Followers per target. Default 1.

Cost = targets × quantity × price, charged upfront; unfilled part is refunded.

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}'

📋 Response Examples

✅ Success

Valid targets accepted, charged, returns orders & balance.

{
  "success": true,
  "message": "成功 1 条，失败 0 条",
  "accepted_count": 1,
  "rejected_count": 0,
  "quantity_per_target": 100,
  "unit_price": 0.001,
  "charged": 0.1000,          // charged this time
  "balance": 9.9000,          // balance after
  "orders": [
    {"id": "57e34a3a3e1d478a", "username": "kinlock", "quantity": 100, "status": "pending"}
  ],
  "rejected": []
}

⚠️ Partially accepted

Valid → orders; invalid → rejected (echoed + reason). Only valid ones are charged.

{
  "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 链接"}
  ]
}

❌ All rejected

{
  "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 链接"} ]
}

💸 Insufficient balance

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

🔑 Invalid key

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

⏱️ Rate limited

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

Limit: 5 req/sec per key. On 429, retry after Retry-After seconds.

🔍 Query Orders

GET /api/v1/orders

Optional params: 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"

Response

{
  "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 (incl. partial+refund). done = completed count, quantity = requested.

💻 Python Example

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

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

# order: 100 followers for kinlock
r = requests.post(f"{BASE}/api/v1/upload", headers=h,
    json={"data": "https://www.instagram.com/kinlock", "quantity": 100})
print(r.json())   # see charged/balance/orders

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