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

​
检查信用余额

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

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

​
响应

{
  "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 <API-TOKEN>",
        "Content-Type": "application/json",
    },
    json={"credits": 10000},
)
print(response.status_code)
print(response.json())

​
要求

  • 团队必须有一个 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。

​
常见错误

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