modelslab-billing-subscriptions

ModelsLab 账单与订阅

通过 Agent Control Plane API 管理账单、钱包充值、支付方式、订阅和优惠券。

何时使用此技能

• 查看钱包余额并为其充值
• 设置钱包自动充值
• 管理支付方式（添加、设为默认、移除）
• 创建支付链接以便人工辅助结账
• 确认 Stripe Checkout 会话（钱包充值或订阅）
• 查看和下载账单
• 创建、升级、暂停或恢复订阅
• 验证和兑换优惠券
• 更新账单信息（地址、税号）

身份验证

所有账单端点都需要持有者令牌。

Base URL: https://modelslab.com/api/agents/v1
Authorization: Bearer <agent_access_token>

通过 modelslab-account-management 技能或 POST /auth/login 获取令牌。

辅助工具

import requests

BASE = "https://modelslab.com/api/agents/v1"

def headers(token):
    return {"Authorization": f"Bearer {token}"}

账单概览

def get_billing_overview(token):
    """Get billing overview — balance, active subscriptions, recent charges."""
    resp = requests.get(f"{BASE}/billing/overview", headers=headers(token))
    return resp.json()["data"]

# Usage
overview = get_billing_overview(token)
print(f"Wallet balance: ${overview.get('wallet_balance', 0)}")

三种支付方式

ModelsLab 支持 Agent 通过以下三种方式处理支付：

方式	最适用于	流程
无头模式	持有卡片数据的自主 Agent	GET /billing/stripe-config -> 通过 Stripe API 进行令牌化 -> 将 payment_method_id 传递给充值/订阅
Setup Intent	保存卡片以供重复使用，无需立即扣款	POST /billing/setup-intent -> 使用 Stripe 确认 -> 重复使用 payment_method_id 进行后续充值/订阅
人工辅助	无法直接处理卡片数据的 Agent	POST /billing/payment-link -> 将 URL 转发给人工用户 -> 用户在 Stripe Checkout 上付款 -> 轮询 confirm-checkout

Stripe 配置

动态获取 Stripe 可发布密钥，而不是将其硬编码。适用于需要在客户端对卡片进行令牌化的 Agent。

def get_stripe_config(token):
    """Get the Stripe publishable key for client-side card tokenization.

    Returns:
        publishable_key: Stripe publishable key (pk_...)
        instructions: Usage guidance from the API
    """
    resp = requests.get(f"{BASE}/billing/stripe-config", headers=headers(token))
    return resp.json()["data"]

# Usage
config = get_stripe_config(token)
stripe_pk = config["publishable_key"]  # e.g., "pk_live_..."

提示： 可发布密钥可以安全地嵌入 Agent 代码中——它只能创建令牌，无法直接扣款。你可以通过此端点动态获取，也可以使用下方硬编码的密钥。

无头卡片令牌化（推荐）

Agent 使用 ModelsLab 可发布密钥直接通过 Stripe API 创建 PaymentMethod。卡片数据只会发送给 Stripe——ModelsLab 不会看到原始卡号。

通过 GET /billing/stripe-config 动态获取 Stripe 可发布密钥。这样可以确保 Agent 始终使用当前密钥，密钥轮换时无需重新部署。

import requests

# Fetch publishable key from API
config_resp = requests.get(
    f"{BASE}/billing/stripe-config",
    headers={"Authorization": f"Bearer {TOKEN}"}
)
STRIPE_PK = config_resp.json()["publishable_key"]

def create_payment_method(card_number, exp_month, exp_year, cvc):
    """Create a Stripe PaymentMethod directly — card data never touches ModelsLab.

    Args:
        card_number: Card number (e.g., "4242424242424242")
        exp_month: Expiry month (e.g., 12)
        exp_year: Expiry year (e.g., 2027)
        cvc: CVC code (e.g., "123")

    Returns:
        Stripe PaymentMethod ID (pm_...) for use with ModelsLab endpoints.
    """
    resp = requests.post(
        "https://api.stripe.com/v1/payment_methods",
        auth=(STRIPE_PK, ""),
        data={
            "type": "card",
            "card[number]": card_number,
            "card[exp_month]": exp_month,
            "card[exp_year]": exp_year,
            "card[cvc]": cvc,
        }
    )
    return resp.json()["id"]  # e.g., "pm_1Xyz..."

# Usage — complete headless payment flow:
pm_id = create_payment_method("4242424242424242", 12, 2027, "123")
fund_wallet(token, 25, payment_method_id=pm_id)  # or create_subscription(...)

Setup Intent 流程

使用 SetupIntent 保存卡片以供日后使用，无需立即扣款。确认后的 PaymentMethod 可重复用于钱包充值或订阅。

def create_setup_intent(token):
    """Create a Stripe SetupIntent to save a card for future use.

    Returns:
        client_secret: Use with Stripe.js or Stripe API to confirm the SetupIntent
        setup_intent_id: The SetupIntent ID (seti_...)
    """
    resp = requests.post(f"{BASE}/billing/setup-intent", headers=headers(token))
    return resp.json()["data"]

# Usage — save a card for reuse
setup = create_setup_intent(token)
client_secret = setup["client_secret"]

# Confirm the SetupIntent via Stripe API with card details
stripe_pk = get_stripe_config(token)["publishable_key"]
confirm_resp = requests.post(
    f"https://api.stripe.com/v1/setup_intents/{setup['setup_intent_id']}/confirm",
    auth=(stripe_pk, ""),
    data={
        "payment_method_data[type]": "card",
        "payment_method_data[card][number]": "4242424242424242",
        "payment_method_data[card][exp_month]": 12,
        "payment_method_data[card][exp_year]": 2027,
        "payment_method_data[card][cvc]": "123",
    }
)
pm_id = confirm_resp.json()["payment_method"]  # e.g., "pm_..."

# Now attach and reuse the payment method
add_payment_method(token, pm_id, make_default=True)
fund_wallet(token, 50, payment_method_id=pm_id)

人工辅助支付（支付链接）

对于无法直接处理卡片数据的 Agent（例如聊天机器人、语音助手），可创建由 Stripe 托管的支付 URL 并转发给人工用户。ModelsLab 控制 success_url——Agent 无法覆盖此设置。

def create_payment_link(token, purpose, amount=None, plan_id=None):
    """Create a Stripe-hosted payment URL for a human to complete.

    Args:
        purpose: "fund" for wallet funding, "subscribe" for subscription
        amount: Required if purpose is "fund" — amount in USD (min $10)
        plan_id: Required if purpose is "subscribe" — plan ID from list_plans()

    Returns:
        payment_url: Stripe Checkout URL to forward to the human
        session_id: Checkout session ID (cs_...) for confirming later
        purpose: Echoed back
        amount: Echoed back (for fund)
        expires_at: When the payment link expires
        instructions: Guidance for the agent

    Note:
        success_url is NOT accepted — ModelsLab controls redirects.
        After payment, the human sees ModelsLab's success page with the session_id
        to copy back to the agent.
    """
    payload = {"purpose": purpose}
    if amount is not None:
        payload["amount"] = amount
    if plan_id is not None:
        payload["plan_id"] = plan_id

    resp = requests.post(
        f"{BASE}/billing/payment-link",
        headers=headers(token),
        json=payload
    )
    return resp.json()["data"]

# Usage — wallet funding via human
link = create_payment_link(token, purpose="fund", amount=50)
print(f"Please complete payment at: {link['payment_url']}")
print(f"Session ID: {link['session_id']} (expires {link['expires_at']})")

# Usage — subscription via human
plans = list_plans(token)
chosen_plan = plans["subscription_plans"][0]
link = create_payment_link(token, purpose="subscribe", plan_id=chosen_plan["id"])
print(f"Please subscribe at: {link['payment_url']}")

确认 Checkout 会话

人工用户在 Stripe Checkout 页面完成支付后，确认会话以完成交易。使用 create_payment_link() 返回的 session_id，或使用人工用户看到成功页面后提供的 session_id。

def confirm_wallet_checkout(token, session_id):
    """Confirm a Stripe Checkout session for wallet funding.

    Call this after the human completes payment on the Stripe Checkout page.

    Args:
        session_id: The Checkout session ID (cs_...) from create_payment_link()
    """
    resp = requests.post(
        f"{BASE}/wallet/confirm-checkout",
        headers=headers(token),
        json={"session_id": session_id}
    )
    return resp.json()["data"]

def confirm_subscription_checkout(token, session_id):
    """Confirm a Stripe Checkout session for subscription.

    Call this after the human completes payment on the Stripe Checkout page.

    Args:
        session_id: The Checkout session ID (cs_...) from create_payment_link()
    """
    resp = requests.post(
        f"{BASE}/subscriptions/confirm-checkout",
        headers=headers(token),
        json={"session_id": session_id}
    )
    return resp.json()["data"]

# Usage — complete human-assisted wallet funding flow
link = create_payment_link(token, purpose="fund", amount=50)
print(f"Pay here: {link['payment_url']}")
# ... human pays ...
session_id = link["session_id"]  # or human copies it from success page
result = confirm_wallet_checkout(token, session_id)
print(f"Wallet funded! New balance: ${result.get('balance')}")

# Usage — complete human-assisted subscription flow
link = create_payment_link(token, purpose="subscribe", plan_id=42)
print(f"Subscribe here: {link['payment_url']}")
# ... human pays ...
result = confirm_subscription_checkout(token, link["session_id"])
print(f"Subscription active! Status: {result.get('status')}")

支付方式

列出支付方式

def list_payment_methods(token):
    """List all saved payment methods."""
    resp = requests.get(f"{BASE}/billing/payment-methods", headers=headers(token))
    return resp.json()["data"]

添加支付方式

def add_payment_method(token, payment_method_id, make_default=True):
    """Add a Stripe payment method.

    Args:
        payment_method_id: Stripe PaymentMethod ID (pm_...)
        make_default: Set as default payment method
    """
    resp = requests.post(
        f"{BASE}/billing/payment-methods",
        headers=headers(token),
        json={
            "payment_method_id": payment_method_id,
            "make_default": make_default
        }
    )
    return resp.json()["data"]

设为默认并移除

def set_default_payment_method(token, payment_method_id):
    """Set a payment method as the default."""
    requests.put(
        f"{BASE}/billing/payment-methods/{payment_method_id}/default",
        headers=headers(token)
    )

def remove_payment_method(token, payment_method_id):
    """Remove a payment method."""
    requests.delete(
        f"{BASE}/billing/payment-methods/{payment_method_id}",
        headers=headers(token)
    )

账单信息

def get_billing_info(token):
    """Get billing name, address, and tax ID."""
    resp = requests.get(f"{BASE}/billing/info", headers=headers(token))
    return resp.json()["data"]

def update_billing_info(token, **kwargs):
    """Update billing information.

    Kwargs: name, email, tax_id, tax_id_type,
            address_line1, address_line2, address_city,
            address_state, address_postal_code, address_country
    """
    resp = requests.put(
        f"{BASE}/billing/info",
        headers=headers(token),
        json=kwargs
    )
    return resp.json()["data"]

# Usage
update_billing_info(
    token,
    name="Acme Corp",
    email="[email protected]",
    tax_id="EU123456789",
    tax_id_type="eu_vat",
    address_line1="123 AI Street",
    address_city="San Francisco",
    address_state="CA",
    address_postal_code="94105",
    address_country="US"
)

账单

def list_invoices(token):
    """List all invoices."""
    resp = requests.get(f"{BASE}/billing/invoices", headers=headers(token))
    return resp.json()["data"]

def get_invoice(token, invoice_id):
    """Get invoice details."""
    resp = requests.get(
        f"{BASE}/billing/invoices/{invoice_id}",
        headers=headers(token)
    )
    return resp.json()["data"]

def get_invoice_pdf(token, invoice_id):
    """Get invoice PDF download URL."""
    resp = requests.get(
        f"{BASE}/billing/invoices/{invoice_id}/pdf",
        headers=headers(token)
    )
    return resp.json()["data"]

钱包

钱包余额

def get_wallet_balance(token):
    """Quick wallet balance check."""
    resp = requests.get(f"{BASE}/wallet/balance", headers=headers(token))
    return resp.json()["data"]

# Usage
balance = get_wallet_balance(token)
print(f"Balance: ${balance['balance']} {balance['currency']}")

钱包交易

def get_wallet_transactions(token, type=None, limit=50, offset=0):
    """Get wallet transaction ledger (deposits, charges, refunds).

    Args:
        type: Filter by "credit" or "debit" (optional)
        limit: Max items 1-200 (default 50)
        offset: Pagination offset (default 0)
    """
    params = {"limit": limit, "offset": offset}
    if type: params["type"] = type

    resp = requests.get(
        f"{BASE}/wallet/transactions",
        headers=headers(token),
        params=params
    )
    return resp.json()["data"]

# Usage
txns = get_wallet_transactions(token, type="debit", limit=20)
for txn in txns["items"]:
    print(f"{txn['created_at']}: {txn['type']} ${txn['amount']} — {txn['usecase']}")
print(f"Wallet balance: ${txns['wallet']['balance']}")

钱包充值

def fund_wallet(token, amount, payment_method_id=None, idempotency_key=None):
    """Add funds to wallet.

    Args:
        amount: Amount in USD (min $10)
        payment_method_id: Stripe PM ID from create_payment_method() (recommended)
        idempotency_key: Prevent duplicate charges on retries (optional)
    """
    payload = {"amount": amount}
    if payment_method_id:
        payload["payment_method_id"] = payment_method_id

    h = headers(token)
    if idempotency_key:
        h["Idempotency-Key"] = idempotency_key

    resp = requests.post(f"{BASE}/wallet/fund", headers=h, json=payload)
    return resp.json()["data"]

# Usage — headless payment flow
pm_id = create_payment_method("4242424242424242", 12, 2027, "123")
fund_wallet(token, 50, payment_method_id=pm_id, idempotency_key="fund-50-20260220")

检查支付状态

def get_payment_status(token, payment_intent_id):
    """Check the status of a Stripe PaymentIntent."""
    resp = requests.get(
        f"{BASE}/payments/{payment_intent_id}/status",
        headers=headers(token)
    )
    return resp.json()["data"]

# Usage
status = get_payment_status(token, "pi_xxx")
print(f"Payment status: {status['status']}")

自动充值

def enable_auto_funding(token, auto_charge_amount, charge_threshold):
    """Enable automatic wallet recharge.

    Args:
        auto_charge_amount: Amount to charge (min $5)
        charge_threshold: Balance threshold to trigger charge (min $1)
    """
    resp = requests.put(
        f"{BASE}/wallet/auto-funding",
        headers=headers(token),
        json={
            "auto_charge_amount": auto_charge_amount,
            "charge_threshold": charge_threshold
        }
    )
    return resp.json()["data"]

def disable_auto_funding(token):
    """Disable automatic wallet recharge."""
    requests.delete(f"{BASE}/wallet/auto-funding", headers=headers(token))

# Usage — auto-charge $25 when balance drops below $5
enable_auto_funding(token, auto_charge_amount=25, charge_threshold=5)

提现

def withdraw(token, amount):
    """Withdraw from wallet balance."""
    resp = requests.post(
        f"{BASE}/wallet/withdraw",
        headers=headers(token),
        json={"amount": amount}
    )
    return resp.json()["data"]

优惠券

def validate_coupon(token, coupon_code, purchase_amount=None):
    """Validate a coupon code before redeeming (GET request)."""
    params = {"coupon_code": coupon_code}
    if purchase_amount:
        params["purchase_amount"] = purchase_amount

    resp = requests.get(
        f"{BASE}/wallet/coupons/validate",
        headers=headers(token),
        params=params
    )
    return resp.json()["data"]

def redeem_coupon(token, coupon_code, payment_method_id=None, purchase_amount=None):
    """Redeem a coupon code."""
    payload = {"coupon_code": coupon_code}
    if payment_method_id:
        payload["payment_method_id"] = payment_method_id
    if purchase_amount:
        payload["purchase_amount"] = purchase_amount

    resp = requests.post(
        f"{BASE}/wallet/coupons/redeem",
        headers=headers(token),
        json=payload
    )
    return resp.json()["data"]

# Usage
info = validate_coupon(token, "WELCOME50")
if not info.get("error"):
    redeem_coupon(token, "WELCOME50")

订阅

查找可用方案

创建订阅之前，先查找可用方案和按需付费选项：

def list_plans(token):
    """List all available subscription plans and pay-as-you-go options.

    Returns:
        subscription_plans: Array of plans with id, name, price, features
        pay_as_you_go: Info about wallet-based billing (min $10 topup, auto-payments)
    """
    resp = requests.get(f"{BASE}/subscriptions/plans", headers=headers(token))
    return resp.json()["data"]

# Usage
plans_data = list_plans(token)

# Show subscription plans
for plan in plans_data["subscription_plans"]:
    print(f"{plan['name']} - ${plan['price']}/{plan['period']} (ID: {plan['id']})")
    print(f"  Features: {', '.join(plan['features'])}")

# Show pay-as-you-go option
payg = plans_data["pay_as_you_go"]
if payg["available"]:
    print(f"\nPay-as-you-go: min ${payg['minimum_topup_usd']} topup")
    print(f"Auto-payments: {payg['auto_payments']['supported']}")

列出订阅

def list_subscriptions(token):
    """List all active subscriptions."""
    resp = requests.get(f"{BASE}/subscriptions", headers=headers(token))
    return resp.json()["data"]

创建订阅

def create_subscription(token, plan_id, success_url=None):
    """Start a new subscription. Returns a Stripe checkout URL.

    Use list_plans() first to discover valid plan IDs.

    Args:
        plan_id: The plan ID from list_plans() response
        success_url: Redirect after successful checkout
    """
    payload = {"plan_id": plan_id}
    if success_url: payload["success_url"] = success_url

    resp = requests.post(
        f"{BASE}/subscriptions",
        headers=headers(token),
        json=payload
    )
    return resp.json()["data"]

# Usage — discover plans, then subscribe
plans = list_plans(token)
chosen_plan = plans["subscription_plans"][0]  # Pick a plan
result = create_subscription(token, chosen_plan["id"])
print(f"Checkout URL: {result['checkout_url']}")

创建订阅（无头模式 — 推荐）

使用 Stripe API 返回的 payment_method_id 以无头模式订阅。无需重定向到 Checkout。

def create_subscription_headless(token, plan_id, payment_method_id, idempotency_key=None):
    """Create a subscription headlessly with a Stripe PaymentMethod.

    No browser redirect — fully headless.
    Use list_plans() first to discover valid plan IDs.
    Use create_payment_method() to get a pm_id from Stripe.

    Args:
        plan_id: The plan ID from list_plans() response
        payment_method_id: Stripe PM ID from create_payment_method()
        idempotency_key: Prevent duplicate subscriptions on retries (optional)
    """
    h = headers(token)
    if idempotency_key:
        h["Idempotency-Key"] = idempotency_key

    resp = requests.post(
        f"{BASE}/subscriptions",
        headers=h,
        json={
            "plan_id": plan_id,
            "payment_method_id": payment_method_id
        }
    )
    return resp.json()["data"]

# Usage — full headless flow
pm_id = create_payment_method("4242424242424242", 12, 2027, "123")
plans = list_plans(token)
chosen_plan = plans["subscription_plans"][0]
result = create_subscription_headless(token, chosen_plan["id"], pm_id)
print(f"Status: {result['status']}")

检查订阅状态

def get_subscription_status(token, subscription_id):
    """Check the current status of a subscription."""
    resp = requests.get(
        f"{BASE}/subscriptions/{subscription_id}/status",
        headers=headers(token)
    )
    return resp.json()["data"]

更新（升级/降级）

def update_subscription(token, subscription_id, new_plan_id):
    """Change a subscription to a different plan."""
    resp = requests.put(
        f"{BASE}/subscriptions/{subscription_id}",
        headers=headers(token),
        json={"new_plan_id": new_plan_id}
    )
    return resp.json()["data"]

暂停与恢复

def pause_subscription(token, subscription_id):
    """Pause a subscription."""
    resp = requests.post(
        f"{BASE}/subscriptions/{subscription_id}/pause",
        headers=headers(token)
    )
    return resp.json()["data"]

def resume_subscription(token, subscription_id):
    """Resume a paused subscription."""
    resp = requests.post(
        f"{BASE}/subscriptions/{subscription_id}/resume",
        headers=headers(token)
    )
    return resp.json()["data"]

其他订阅操作

def reset_subscription_cycle(token, subscription_id):
    """Reset the current billing cycle."""
    requests.post(
        f"{BASE}/subscriptions/{subscription_id}/reset-cycle",
        headers=headers(token)
    )

def charge_subscription_amount(token, amount):
    """Charge a custom amount ($5-$10,000)."""
    resp = requests.post(
        f"{BASE}/subscriptions/charge-amount",
        headers=headers(token),
        json={"amount": amount}
    )
    return resp.json()["data"]

def fix_payment(token, subscription_id):
    """Fix a failed subscription payment."""
    requests.post(
        f"{BASE}/subscriptions/{subscription_id}/fix-payment",
        headers=headers(token)
    )

常见工作流：确保账户有资金

def ensure_account_funded(token, min_balance=10, top_up_amount=50):
    """Check wallet balance and fund if low."""
    overview = get_billing_overview(token)
    balance = overview.get("wallet_balance", 0)

    if balance < min_balance:
        print(f"Balance ${balance} below ${min_balance}, funding ${top_up_amount}...")
        fund_wallet(token, top_up_amount)
        print("Wallet funded!")
    else:
        print(f"Balance OK: ${balance}")

# Usage
ensure_account_funded(token, min_balance=5, top_up_amount=25)

常见工作流：人工辅助充值并轮询

import time

def fund_via_human(token, amount, poll_interval=5, max_wait=300):
    """Create a payment link and poll until the human completes it.

    Args:
        amount: Amount in USD
        poll_interval: Seconds between balance checks
        max_wait: Maximum seconds to wait before giving up
    """
    # Get initial balance
    initial = get_wallet_balance(token)["balance"]

    # Create payment link
    link = create_payment_link(token, purpose="fund", amount=amount)
    print(f"Please fund your wallet at: {link['payment_url']}")
    print(f"Waiting for payment (expires {link['expires_at']})...")

    # Poll for confirmation
    elapsed = 0
    while elapsed < max_wait:
        time.sleep(poll_interval)
        elapsed += poll_interval
        try:
            result = confirm_wallet_checkout(token, link["session_id"])
            print(f"Payment confirmed! New balance: ${result.get('balance')}")
            return result
        except Exception:
            # Session not yet completed, keep polling
            pass

    print("Payment not completed within timeout.")
    return None

# Usage
fund_via_human(token, amount=50, max_wait=600)

MCP 服务访问

这些相同的功能也可通过 Agent Control Plane MCP 服务使用：

• URL：https://modelslab.com/mcp/agents
• 工具：agent-billing、agent-wallet、agent-subscriptions（使用 list-plans 操作来查找方案）

参见：https://docs.modelslab.com/mcp-web-api/agent-control-plane

API 端点参考

方法	端点	描述
GET	/billing/overview	账单概览
GET	/billing/stripe-config	获取 Stripe 可发布密钥
POST	/billing/setup-intent	创建用于保存卡片的 SetupIntent
POST	/billing/payment-link	创建 Stripe Checkout 付款 URL
GET	/billing/payment-methods	列出付款方式
POST	/billing/payment-methods	添加付款方式
PUT	/billing/payment-methods/{id}/default	设为默认项
DELETE	/billing/payment-methods/{id}	移除付款方式
GET	/billing/info	获取账单信息
PUT	/billing/info	更新账单信息
GET	/billing/invoices	列出发票
GET	/billing/invoices/{id}	发票详情
GET	/billing/invoices/{id}/pdf	发票 PDF URL
GET	/wallet/balance	快速查看钱包余额
GET	/wallet/transactions	钱包交易明细
POST	/wallet/fund	为钱包充值（使用 payment_method_id）
POST	/wallet/confirm-checkout	确认 Checkout 钱包充值
PUT	/wallet/auto-funding	启用自动充值
DELETE	/wallet/auto-funding	禁用自动充值
POST	/wallet/withdraw	提取余额
GET	/wallet/coupons/validate	验证优惠券
POST	/wallet/coupons/redeem	兑换优惠券
GET	/payments/{id}/status	检查付款意图状态
GET	/subscriptions/plans	列出可用方案及按需付费选项
GET	/subscriptions	列出订阅（addon、enterprise、normal）
POST	/subscriptions	创建订阅（使用 pm_id 的无头模式，或使用 Checkout）
POST	/subscriptions/confirm-checkout	确认 Checkout 订阅
GET	/subscriptions/{id}/status	检查订阅状态
PUT	/subscriptions/{id}	更新订阅
POST	/subscriptions/{id}/pause	暂停
POST	/subscriptions/{id}/resume	恢复
POST	/subscriptions/{id}/reset-cycle	重置周期
POST	/subscriptions/charge-amount	扣取金额
POST	/subscriptions/{id}/fix-payment	修复付款

最佳实践

1. 选择合适的付款路径

# Headless — agent has card data, fully autonomous
pm_id = create_payment_method("4242424242424242", 12, 2027, "123")
fund_wallet(token, 50, payment_method_id=pm_id)

# Setup Intent — save card first, charge later
setup = create_setup_intent(token)
# ... confirm with Stripe API ...
add_payment_method(token, pm_id, make_default=True)

# Human-Assisted — agent cannot handle cards
link = create_payment_link(token, purpose="fund", amount=50)
# Forward link['payment_url'] to human, then confirm_wallet_checkout()

2. 为账单操作使用幂等键

# Prevent duplicate charges on retries
fund_wallet(token, 50, payment_method_id=pm_id, idempotency_key="fund-50-unique-key")

3. 设置自动充值

# Avoid running out of credits during generation
enable_auto_funding(token, auto_charge_amount=25, charge_threshold=5)

4. 执行大型任务前检查余额

balance = get_wallet_balance(token)
if balance["balance"] < estimated_cost:
    fund_wallet(token, estimated_cost * 1.2)  # 20% buffer

5. 兑换前验证优惠券

info = validate_coupon(token, code)
# Check discount amount, expiry, etc. before committing

6. 妥善处理银行卡付款失败

result = fund_wallet(token, 50, payment_method_id=pm_id)
# Check for errors
if result.get("error"):
    if result["error"]["code"] == "payment_declined":
        print(f"Card declined: {result['error']['details']['decline_code']}")
    # Try a different card or ask user

资源

• API 文档：https://docs.modelslab.com/agents-api/billing-and-wallet
• MCP 服务：https://docs.modelslab.com/mcp-web-api/agent-control-plane
• 定价：https://modelslab.com/pricing
• 控制面板：https://modelslab.com/dashboard

相关技能

• modelslab-account-management - 账户设置和 API 密钥
• modelslab-model-discovery - 检查用量并查找模型
• modelslab-webhooks - 用于异步结果的逐请求 webhook URL