Follow Order System
中文 EN 登录

API 文档

API 地址 https://ystarr.com

所有 API 请求都发送到这个地址。请勿把网页地址和 API 地址混淆。

Instagram 关注与 Facebook 直播人气接口已分开说明。所有请求需带请求头 X-API-Key: 你的KEY

🔑 认证

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

X-API-Key: 你的KEY

认证失败示例

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

💰 查询余额

GET /api/v1/balance

curl "https://ystarr.com/api/v1/balance" -H "X-API-Key: 你的KEY"

返回

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

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

📸 Instagram 关注下单

POST /api/v1/upload

字段说明
dataInstagram 链接文本，可多个拼接。只接受 instagram.com 链接。
quantity每个目标要关注的数量(粉丝数)。默认 1。
daily_limit每个目标【每天】最多关注多少个，用于控制速度（如一天只涨 300）。0 或不填=不限速，一次做完。

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

示例1：一次做完（不限速）

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

示例2：慢速涨粉（1500个粉丝，每天最多300，约5天做完）

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

daily_limit=300 表示这个目标每天最多涨 300 个粉丝，达到当天上限后自动暂停，第二天继续，直到做满 quantity。

📋 Instagram 下单返回示例

✅ 成功

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

{
  "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, "daily_limit": 300, "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 秒后重试。

🔍 Instagram 订单状态

GET /api/v1/orders

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

curl "https://ystarr.com/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=需求数。

🛒 第 1 步：获取 Facebook 商品 ID

GET /api/v1/products

先请求此接口。返回列表中 id 就是下单时要填写的 product_id。只能看到当前 Key 有权限使用的上架商品。

curl "https://ystarr.com/api/v1/products" \
  -H "X-API-Key: 你的KEY"

返回示例

{
  "success": true,
  "products": [
    {
      "id": "prd_a1b2c3d4e5f67890",
      "name": "Facebook 直播人气",
      "service_type": "facebook_live_popularity",
      "price": "0.001",
      "min_quantity": "1000",
      "max_quantity": "10000",
      "min_duration_minutes": "60",
      "max_duration_minutes": "1440"
    }
  ]
}

上例中，下单使用：product_id = "prd_a1b2c3d4e5f67890"。请使用接口实际返回的 ID，不要手写 prd_xxx。

🔴 第 2 步：Facebook 直播人气下单

POST /api/v1/product-orders

字段说明
product_id上一步商品列表返回的 id。
target_urlFacebook 直播间或直播视频链接。
quantity需要的人气数量，必须在商品的最小/最大数量范围内。
duration_minutes在线时长（分钟），必须在商品的时长范围内。

下单示例：1000 人气，在线 60 分钟

curl -X POST "https://ystarr.com/api/v1/product-orders" \
  -H "X-API-Key: 你的KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_a1b2c3d4e5f67890",
    "target_url": "https://www.facebook.com/your-page/videos/123456789",
    "quantity": 1000,
    "duration_minutes": 60
  }'

订单编号由系统下单成功后自动生成并返回。费用由后台商品价格计算；服务端会校验 Key 权限、商品、链接、数量、时长和余额。

📋 Facebook 下单返回示例

✅ 下单成功

{
  "success": true,
  "product_id": "prd_a1b2c3d4e5f67890",
  "charged": 1.0000,
  "balance": 9.0000,
    "order": {
      "id": "a8b9c0d1e2f34567",
      "order_no": "FB20260914183045A1B2C3D4",
      "created_at": "2026-09-14 18:30:45",
      "status": "pending",
      "quantity": 1000,
      "duration_minutes": 60
  }
}

💸 余额不足

HTTP 402
{"detail": "余额不足，订单未创建"}

🚫 无商品权限

HTTP 403
{"detail": "当前 API Key 没有该商品的下单权限"}

🔍 Facebook 订单状态

GET /api/v1/facebook/orders/{order_no}

下单成功后保存返回的 order_no。可用 order_no 或内部 id 查询单个订单；只能查询当前 API Key 自己创建的 Facebook 订单。

curl "https://ystarr.com/api/v1/facebook/orders/FB20260914183045A1B2C3D4" \
  -H "X-API-Key: 你的KEY"

返回示例

{
  "success": true,
  "order": {
    "id": "a8b9c0d1e2f34567",
    "order_no": "FB20260914183045A1B2C3D4",
    "created_at": "2026-09-14 18:30:45",
    "status": "processing",
    "target_url": "https://www.facebook.com/your-page/videos/123456789",
    "quantity": "1000",
    "done": "760",
    "duration_minutes": "60",
    "updated_at": "2026-09-14 18:42:10"
  }
}

GET /api/v1/facebook/orders 可返回当前 Key 的全部 Facebook 订单，并支持 status_filter、start、end 参数。

💻 Python 完整 Facebook 示例

import requests
BASE = "https://ystarr.com"
KEY  = "你的KEY"
h = {"X-API-Key": KEY}

# 第 1 步：获取商品，找到 Facebook 商品的 id
products = requests.get(f"{BASE}/api/v1/products", headers=h).json()["products"]
facebook_product = next(p for p in products if p["service_type"] == "facebook_live_popularity")
product_id = facebook_product["id"]

# 第 2 步：下单 1000 人气，在线 60 分钟
r = requests.post(f"{BASE}/api/v1/product-orders", headers=h,
    json={"product_id": product_id,
          "target_url": "https://www.facebook.com/your-page/videos/123456789",
          "quantity": 1000, "duration_minutes": 60})
print(r.json())

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