API Documentation

🔑 Authentication

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

X-API-Key: YOUR_API_KEY

Auth failure

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

💰 Check Balance

GET /api/v1/balance

curl "https://ystarr.com/api/v1/balance" -H "X-API-Key: YOUR_API_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.

📸 Instagram Follow Order

POST /api/v1/upload

Field	Description
data	Instagram links text (multiple ok). Only instagram.com links accepted.
quantity	Followers per target. Default 1.
daily_limit	Max followers per target PER DAY (rate control, e.g. 300/day). 0 or omit = no limit.

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

Example 1: no rate limit

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

Example 2: slow drip (1500 total, max 300/day, ~5 days)

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

daily_limit=300 means this target gains at most 300 followers/day; it auto-pauses when the daily cap is hit and resumes next day until quantity is filled.

📋 Instagram Order Responses

✅ Success

Valid targets accepted, charged, returns orders & balance.

{
  "success": true,
  "message": "1 accepted, 0 rejected",
  "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, "daily_limit": 300, "status": "pending"}
  ],
  "rejected": []
}

⚠️ Partially accepted

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

{
  "success": true,
  "message": "1 accepted, 1 rejected",
  "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"}
  ]
}

❌ All rejected

{
  "success": false,
  "message": "0 accepted, 1 rejected",
  "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: required $0.1000, available $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.

🔍 Instagram Order Status

GET /api/v1/orders

Optional params: 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: YOUR_API_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.

🛒 Step 1: Get a Facebook Product ID

GET /api/v1/products

Call this endpoint first. In the returned list, copy the value of id; it is the product_id used when placing an order. You only see active products allowed by your API key.

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

Response example

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

For the product above, use: product_id = "prd_a1b2c3d4e5f67890". Use the actual ID returned by the API; do not literally send prd_xxx.

🔴 Step 2: Place a Facebook Live Popularity Order

POST /api/v1/product-orders

Field	Description
product_id	The id returned in Step 1.
target_url	Facebook live room or live video URL.
quantity	Requested audience count; must be within the product minimum and maximum.
duration_minutes	Online duration in minutes; must be within the product duration range.

Order example: 1,000 audience for 60 minutes

curl -X POST "https://ystarr.com/api/v1/product-orders" \
  -H "X-API-Key: YOUR_API_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
  }'

The server generates and returns the order ID after a successful order. The server calculates pricing and validates key permissions, product, URL, quantity, duration, and balance.

📋 Facebook Order Response

✅ Order accepted

{
  "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
  }
}

💸 Insufficient balance

HTTP 402
{"detail": "Insufficient balance; order was not created"}

🚫 No product permission

HTTP 403
{"detail": "This API key is not allowed to order this product"}

🔍 Facebook Order Status

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

Save order_no from the order response. Query by order_no or internal id; an API key can only read its own Facebook orders.

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

Response example

{
  "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 Complete Facebook Example

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

# Step 1: get products and find the Facebook product 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"]

# Step 2: order 1,000 audience for 60 minutes
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())

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