余额与账单

使用用户账单端点来读取团队的信用余额，并使用已保存的支付方式购买充值。这两个端点都需要使用你的 API 密钥进行身份验证。无效的密钥将返回 402。

检查信用余额

GET /user/credits/info 返回已认证团队的信用余额、每批次的详细信息、活跃的订阅详情，以及是否允许使用。使用此端点为账单小部件、使用仪表板或在运行大型作业前进行预检。有关 API 详细信息，请参见获取信用信息。

import requests

response = requests.get(
    "https://api.olostep.com/user/credits/info",
    headers={"Authorization": "Bearer <YOUR_API_KEY>"},
)
print(response.json())

const res = await fetch("https://api.olostep.com/user/credits/info", {
  headers: { Authorization: "Bearer <YOUR_API_KEY>" },
})
console.log(await res.json())

curl -s "https://api.olostep.com/user/credits/info" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

响应

{
  "credits": 12500,
  "breakdown": [
    {
      "purchase_kind": "Subscription",
      "allocated_units": 10000,
      "remaining_units": 8500,
      "expiry_date": 1735689600
    },
    {
      "purchase_kind": "Top-up",
      "allocated_units": 5000,
      "remaining_units": 4000,
      "expiry_date": 1743465600
    }
  ],
  "active_subscription": {
    "id": "SUB_PRO",
    "display_name": "Pro",
    "credits": 10000,
    "created_at": 1704067200
  },
  "allow_usage": true
}

字段	描述
`credits`	所有未过期批次的总剩余信用
`breakdown`	每批次的详细信息：类型、分配和剩余单位、到期日
`active_subscription`	当前计划（如果没有活跃计划则回退到 `SUB_BASE`）
`allow_usage`	团队是否仍然可以使用信用

breakdown 中的每个批次都有一个 purchase_kind，可以是 Subscription、Top-up、Manual、Setup 或 Pending。

购买充值

POST /user/purchase-topup 使用 Stripe 上保存的卡片进行扣款并一步购买信用。没有结账重定向或嵌入的支付 UI。在请求体中传递信用数量：

{ "credits": 10000 }

字段	描述
`credits`	要购买的信用数量

支持的值：10,000、20,000、80,000 和 100,000。有关 API 详细信息，请参见购买充值。

import requests

response = requests.post(
    "https://api.olostep.com/user/purchase-topup",
    headers={
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
    json={"credits": 10000},
)
print(response.status_code)
print(response.json())

const res = await fetch("https://api.olostep.com/user/purchase-topup", {
  method: "POST",
  headers: {
    Authorization: "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ credits: 10000 }),
})
console.log(res.status)
console.log(await res.json())

curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"credits": 10000}'

要求

团队必须有一个 Stripe 客户，并至少保存了一张卡片。
每个团队每 60 秒 只允许一次购买尝试。如果你触发了冷却时间，响应为 429，并带有 Retry-After 头。

响应

200 — 支付成功：

{
  "success": true,
  "payment_intent_id": "pi_xxx",
  "credits": 10000
}

202 — 支付仍在处理中。信用将在 Stripe 确认支付后添加：

{
  "success": true,
  "status": "processing",
  "payment_intent_id": "pi_xxx",
  "message": "Payment is processing. Credits will be added once the payment is confirmed.",
  "credits": 10000
}

信用是在支付确认后由 Stripe webhook 发放的，而不是直接从 HTTP 响应中发放。将 200 视为支付成功；如果需要确认更新的余额，请轮询 GET /user/credits/info。

常见错误

状态	错误	发生时间
400	`missing_topup_selector`	未发送 `credits`
400	`invalid_credits`	信用数量不在允许列表中
400	`no_stripe_customer`	团队没有 Stripe 客户
400	`no_payment_method`	文件中没有保存的卡片
402	`payment_failed`	没有保存的卡片完成扣款
429	`purchase_topup_cooldown`	在 60 秒内尝试了另一次购买
503	`payment_status_unknown`	模糊的 Stripe 错误；等待后重试

自动充值

为了防止余额耗尽，定期检查余额，并在余额低于阈值时购买充值。这使用了上面的两个端点，并可以在任何可以运行脚本的地方工作：cron 作业、CI 步骤、无服务器函数，或在大型作业前的 AI 代理。

调用 GET /user/credits/info 并读取 credits。
如果 credits 低于你的阈值，调用 POST /user/purchase-topup 并传递支持的金额之一。
在 200 或 202 时停止。信用将在 Stripe 确认支付后到达，因此在下次检查前不要再次购买，直到余额更新。

import os
import requests

API = "https://api.olostep.com"
HEADERS = {"Authorization": f"Bearer {os.environ['OLOSTEP_API_KEY']}"}
THRESHOLD = 2000      # 当余额低于此值时充值
TOPUP_CREDITS = 10000  # 10000, 20000, 80000, 或 100000

credits = requests.get(f"{API}/user/credits/info", headers=HEADERS).json()["credits"]

if credits < THRESHOLD:
    res = requests.post(
        f"{API}/user/purchase-topup",
        headers=HEADERS,
        json={"credits": TOPUP_CREDITS},
    )
    print(res.status_code, res.json())
else:
    print(f"Balance OK: {credits} credits")

const API = "https://api.olostep.com"
const headers = {
  Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}`,
  "Content-Type": "application/json",
}
const THRESHOLD = 2000 // 当余额低于此值时充值
const TOPUP_CREDITS = 10000 // 10000, 20000, 80000, 或 100000

const { credits } = await (await fetch(`${API}/user/credits/info`, { headers })).json()

if (credits < THRESHOLD) {
  const res = await fetch(`${API}/user/purchase-topup`, {
    method: "POST",
    headers,
    body: JSON.stringify({ credits: TOPUP_CREDITS }),
  })
  console.log(res.status, await res.json())
} else {
  console.log(`Balance OK: ${credits} credits`)
}

#!/usr/bin/env bash
# 需要 jq。当余额低于 THRESHOLD 时充值。
THRESHOLD=2000
TOPUP_CREDITS=10000

credits=$(curl -s "https://api.olostep.com/user/credits/info" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" | jq '.credits')

if [ "$credits" -lt "$THRESHOLD" ]; then
  curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"credits\": $TOPUP_CREDITS}"
else
  echo "Balance OK: $credits credits"
fi

使用 cron 每小时运行一次检查：

0 * * * * OLOSTEP_API_KEY=your_key /usr/bin/python3 /path/to/refill.py

选择一个能覆盖检查间隔内使用量的阈值。如果你每小时运行一次检查，并且每小时使用大约 1,000 个信用，2,000 的阈值在充值处理中留有缓冲。

每次运行都可能会扣费。每个团队只运行一个充值作业，并通过等待下一个计划的检查来处理 429（purchase_topup_cooldown）和 503（payment_status_unknown），而不是立即重试。402（payment_failed）表示你的卡片被拒绝；在下次运行前在仪表板中更新它。

Get Started

Features

Balance & Billing

检查信用余额

响应

购买充值

要求

响应

常见错误

自动充值

​检查信用余额

​响应

​购买充值

​要求

​响应

​常见错误

​自动充值

检查信用余额

响应

购买充值

要求

响应

常见错误

自动充值