Skip to content

Account

Activation, balance, top-up, keys and tier management.

1. Overview

Base path: https://api.infrai.cc/v1/account
Auth header: Authorization: Bearer $INFRAI_API_KEY
bash
# Call any /v1/account capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/account/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

2. Methods (29)

2.1account.balance

GET /v1/account/balance

Read the wallet balance.

Returns

{ balance_usd, currency }
NameTypeDescription
balancenumberCurrent wallet balance in USD
≥ 0
capnumber | nullWallet upper bound for current tier; null for Enterprise (no cap).
≥ 0
available_roomnumber | null= cap - balance; null when cap is null (uncapped).
≥ 0
runway_daysnumber | nullEstimated days at current daily_avg_spend; null when spend rate is ~0.
≥ 0
daily_avg_spendnumberAverage daily spend in USD
≥ 0
tier"standard" | "pro" | "enterprise"Current subscription tier (standard / pro / enterprise)
expires_atstring | nullTrial-credit expiry (last activity + grace window); null when there is no expiring trial credit.
format: date-time
expires_in_daysinteger | nullDays until the current balance or subscription expires
activity_required_bystring | nullDate by which account activity is required to maintain status
format: date-time
is_refundablebooleanWhether the current balance is eligible for refund
is_transferablebooleanWhether the current balance can be transferred to another account
is_in_grace_periodbooleanWhether the account is in the grace period after balance expiry
grace_period_ends_atstring | nullISO 8601 timestamp when the grace period ends
format: date-time
forfeited_amountnumber | nullAmount forfeited during account operations, in USD
≥ 0
pending_topupsstring[] | nullList of pending top-up sessions
account_idstring | nullThe account the balance belongs to.
balance_usdnumberAlias of `balance` for the documented SDK/CLI status surface.
≥ 0
currencystringISO 4217 currency code (e.g. USD, CNY)
e.g. USD
affordable_uses_hintobject | nullPer-capability hint: how many more flat-priced calls the current balance covers (best-effort, omitted for token-metered caps).

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/balance \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.2account.topup

POST /v1/account/topup

Top up the wallet; returns a checkout URL to hand the user — card data never touches infrai.

Parameters

NameTypeRequiredDescription
amount_usdnumber
Required
Top-up amount in USD.
≥ 0
return_urlstringOptionalWhere to return after checkout.
format: uri
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

TopupRecord { topup_id, amount_usd, state, next_action_url? }
NameTypeDescription
topup_idstringProvider checkout-session id (Stripe cs_... / dev cs_mock_...). Pass to account.topup_status to poll the outcome.
status"pending" | "paid" | "failed" | "unknown"pending until the user completes browser checkout; the Stripe webhook flips it to paid/failed.
checkout_urlstringOpen this to pay; on success the wallet is credited.
format: uri
checkout_mode"stripe" | "mock"stripe = real Stripe Checkout; mock = local dev session.
amount_usdnumberTop-up amount in USD.
≥ 0.5
amountnumberBack-compat alias of amount_usd.
≥ 0.5
currencystringISO 4217 currency code (e.g. USD, CNY)
e.g. USD

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/topup \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.3account.keys.list

GET /v1/account/keys/list

List the project keys on the account.

Returns

{ items: Array<{ key_id, label, scopes, created_at }> }
NameTypeDescription
itemsobject[]Array of result items in this page
items[].key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
items[].key_secretstring | nullFull plaintext value; returned only on create.
items[].keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
items[].old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
items[].rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
items[].revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
items[].actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
items[].updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
items[].namestring | nullHuman-readable name for this resource
items[].tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
items[].scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
items[].created_atstringISO 8601 timestamp when this resource was created
format: date-time
items[].last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
items[].last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
items[].expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
items[].revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
items[].status"active" | "rotating" | "revoked" | "not_found"Current status of this resource. 'not_found' is returned by keys.update/.rotate/.suspected_compromise when the referenced key_id doesn't resolve to a key on this account.
next_cursorstring | nullOpaque cursor to fetch the next page; null/absent if this is the last page
countintegerTotal number of items across all pages
≥ 0

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/keys/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.4account.tier.upgrade

POST /v1/account/tier/upgrade

Upgrade the account to a target tier.

Parameters

NameTypeRequiredDescription
target_tierstring
Required
Tier id to upgrade to.

Returns

AccountSummary { account_id, kind, status, tier, balance_usd }
NameTypeDescription
target"pro" | "team" | "enterprise"Target URL or resource for webhook or notification
requires_checkoutbooleanWhether a Stripe checkout session is required to complete the change
checkout_urlstring | nullURL for the Stripe checkout session
format: uri
requires_sales_contactbooleanWhether contacting sales is required to complete the change
contact_sales_urlstring | nullURL to contact the sales team
format: uri
current_tierstring | nullEffective tier before this upgrade.
status"pending" | "active" | nullSubscription lifecycle after the call. pending = awaiting checkout webhook; active = confirmed (dev/non-prod posture).
immediate_effectboolean | nullTrue only when the tier flipped immediately (dev/non-prod posture, no real payment).
price_usdnumber | nullResolved plan price in USD.
periodstring | nullBilling period of the resolved plan (e.g. monthly/annual).
subscriptionobject | nullPublic view of the created subscription (present when confirmed).
subscription_idstring | nullCreated subscription id (present when pending checkout).
payment_source"wallet" | "dev_mock" | "stripe_subscription" | nullHow the upgrade was (or will be) funded: wallet balance, dev/non-prod auto-confirm, or a real Stripe subscription checkout. Absent for the enterprise (sales-contact) branch.
checkout_modestring | nullMode of the created checkout session (e.g. 'stripe'/'mock'). Present only alongside checkout_url (payment_source=stripe_subscription).
account_idstring | nullAccount the upgrade applies to.

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/tier/upgrade \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "pro"}'

2.5account.whoami

GET /v1/account/whoami

获取当前账户概要(账户 ID、类型、状态、档位、余额)。

Returns

AccountSummary { account_id, kind, status, tier, balance_usd }
NameTypeDescription
account_idstringReal ids use a 16-hex device/email suffix (e.g. acct_anon_9424f4c4b31d4908); pattern relaxed to a minimum of 12 hex chars to match the live id format.
pattern: ^acct_(anon|email|unbound)_[A-Z…
account_kind"anonymous" | "email" | "unbound"Identity state of the key holder. `unbound` = key minted by infra.activate() not yet linked to an email; `email` = bound via OTP/Google/GitHub. `anonymous` is a legacy alias for `unbound` (will be retired).
emailstring | nullEmail address
format: email
email_verifiedbooleanWhether the email address has been verified
linked_providers("email_otp" | "google" | "github" | "oauth")[]Identity providers that have verified this email. The same email can be linked via multiple methods (Google + GitHub + OTP) and all resolve to one account. Empty for unbound keys.
display_namestring | nullHuman-readable display name
region"global" | "cn"Geographic region where this resource is located or processed
created_atstring | nullUser-row creation time. Null for unbound keys (no User row yet).
format: date-time
last_active_atstring | nullLatest of last_login_at / updated_at on the User row. Null for unbound keys.
format: date-time
tier"standard" | "pro" | "enterprise"Current subscription tier (standard / pro / enterprise)
kyc_status"none" | "pending" | "approved" | "rejected"Current KYC verification status
totp_enabledbooleanWhether TOTP-based 2FA is enabled for this account
pro_subscriptionobject | nullDetails of the active Pro subscription, if any
enterprise_contractobject | nullDetails of the enterprise contract, if any
device_fingerprintstringDevice fingerprint hash for identity tracking
current_project_key_idstringCurrent project key identifier
project_countintegerNumber of projects in this account
≥ 0
absorbed_anon_account_idsstring[]List of anonymous account IDs absorbed during linking
linked_devices_countintegerNumber of linked device accounts
≥ 0
project_idstring | nullThe project_id the caller's bearer key is bound to. Mirrors api_key.project_id (e.g. `proj_anon_xxx` for an unbound key). Null when the bearer has no project.
key_idstring | nullMasked (non-secret) form of the caller's bearer key — same value as `current_project_key_id`. Kept for compatibility with the original `account.whoami` shape; new callers should read `current_project_key_id`.

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/whoami \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.6account.usage

GET /v1/account/usage

获取本计费周期的用量汇总(消费、请求数、按能力拆分)。

Returns

UsageSummary { period, spend_usd, requests, by_capability }
NameTypeDescription
period"1d" | "7d" | "30d" | "mtd" | "ytd"Billing or retention period (e.g. monthly, daily)
period_startstringStart of the current billing period
format: date-time
period_endstringEnd of the current billing period
format: date-time
total_costnumberTotal cost in USD for the queried period
≥ 0
total_callsintegerTotal number of API calls in the queried period
≥ 0
total_failed_callsintegerTotal number of failed API calls in the queried period
≥ 0
cache_hitsintegerNumber of cache hits in the queried period
≥ 0
cache_savingsnumberEstimated cost savings from cache hits in USD
≥ 0
breakdownobject[]Cost breakdown by component
breakdown[].keystring-
breakdown[].labelstring-
breakdown[].costnumber-
≥ 0
breakdown[].callsinteger-
≥ 0
breakdown[].failed_callsinteger-
≥ 0
breakdown[].avg_latency_msnumber | null-
≥ 0
breakdown[].p95_latency_msnumber | null-
≥ 0
breakdown[].error_ratenumber | null-
0–1
breakdown[].top_errorsobject[] | null-

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/usage \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.7account.usage.timeseries

GET /v1/account/usage/timeseries

按时间粒度获取用量时间序列。

Parameters

NameTypeRequiredDescription
startstringOptional起始时间(ISO 8601),留空则取周期起点。
endstringOptional结束时间(ISO 8601),留空则取当前。
granularity"hour" | "day" | "month"Optional聚合粒度:hour / day / month。

Returns

UsageTimeseries { granularity, points: Array<{ ts, spend_usd, requests }> }
NameTypeDescription
period"1d" | "7d" | "30d" | "mtd" | "ytd"Billing or retention period (e.g. monthly, daily)
bucketsobject[]Time-bucketed data points
buckets[].datestring-
format: date
buckets[].costnumber-
≥ 0
buckets[].callsinteger-
≥ 0
buckets[].failed_callsinteger-
≥ 0
buckets[].cache_hitsinteger | null-
≥ 0
next_cursorstring | nullOpaque cursor to fetch the next page; null/absent if this is the last page

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/usage/timeseries \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.8account.budget.get

GET /v1/account/budget/get

获取当前预算配置(周期、硬上限、告警阈值)。

Returns

BudgetConfig { period, hard_cap_usd?, alert_threshold_usd? }
NameTypeDescription
hard_cap_usdnumber | nullSpend in the period is blocked past this; null = no cap.
≥ 0
limit_usdnumber | nullaccount.budget.set only. Same meaning as hard_cap_usd, echoed under the request field name.
≥ 0
period"daily" | "monthly"Billing or retention period (e.g. monthly, daily)
alert_threshold_usdnumber | nullFire low-balance / budget-near alert at this remaining balance; null = no alert.
≥ 0
alert_threshold_pctnumber | nullaccount.budget.set only. Alert threshold expressed as a percentage of hard_cap_usd, echoed back as set.
≥ 0
spent_this_period_usdnumberAmount spent in the current billing period in USD
≥ 0
period_resets_atstring | nullISO 8601 timestamp when the current period resets
format: date-time
configuredbooleanWhether a budget row has been set (false = no cap configured; the *_usd fields are then null/0).
updated_atstring | nullISO 8601 timestamp when this resource was last updated
format: date-time

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/budget/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.9account.budget.set

PUT /v1/account/budget/set

设置预算:周期内消费达到硬上限即拦截,达到阈值即告警。

Parameters

NameTypeRequiredDescription
period"daily" | "monthly"
Required
预算周期:daily 或 monthly。
hard_cap_usdnumberOptional硬上限(美元),超过即拦截后续计费请求。
≥ 0
alert_threshold_usdnumberOptional告警阈值(美元),达到即触发告警。
≥ 0
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

BudgetConfig { period, hard_cap_usd?, alert_threshold_usd? }
NameTypeDescription
hard_cap_usdnumber | nullSpend in the period is blocked past this; null = no cap.
≥ 0
limit_usdnumber | nullaccount.budget.set only. Same meaning as hard_cap_usd, echoed under the request field name.
≥ 0
period"daily" | "monthly"Billing or retention period (e.g. monthly, daily)
alert_threshold_usdnumber | nullFire low-balance / budget-near alert at this remaining balance; null = no alert.
≥ 0
alert_threshold_pctnumber | nullaccount.budget.set only. Alert threshold expressed as a percentage of hard_cap_usd, echoed back as set.
≥ 0
spent_this_period_usdnumberAmount spent in the current billing period in USD
≥ 0
period_resets_atstring | nullISO 8601 timestamp when the current period resets
format: date-time
configuredbooleanWhether a budget row has been set (false = no cap configured; the *_usd fields are then null/0).
updated_atstring | nullISO 8601 timestamp when this resource was last updated
format: date-time

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X PUT https://api.infrai.cc/v1/account/budget/set \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period": "daily"}'

2.10account.autorecharge.get

GET /v1/account/autorecharge/get

获取自动充值配置。

Returns

AutorechargeConfig { enabled, trigger_balance, recharge_amount, max_per_day, max_per_month }
NameTypeDescription
enabledbooleanWhether this feature or configuration is enabled
trigger_balancenumberBalance threshold that triggers automatic recharge, in USD
≥ 0
recharge_amountnumberAmount to recharge when triggered, in USD
≥ 0
payment_method_idstringIdentifier of the payment method used
payment_method_summarystringe.g. 'Visa ****4242'.
max_per_dayintegerMaximum recharge amount per day in USD
≥ 1
max_per_monthintegerMaximum recharge amount per month in USD
≥ 1
triggered_todayintegerAmount recharged today in USD
≥ 0
triggered_this_monthintegerAmount recharged this month in USD
≥ 0
next_check_atstring | nullISO 8601 timestamp when the next balance check will occur
format: date-time
last_succeeded_atstring | nullISO 8601 timestamp of the last successful payment
format: date-time
last_failed_atstring | nullISO 8601 timestamp of the last payment failure
format: date-time
consecutive_failuresintegerNumber of consecutive payment failures
≥ 0
configuredbooleanWhether a config row exists for this account (false = never set up; the numeric fields are then zero defaults).
disabled_reasonstring | nullWhy auto-recharge is currently disabled (e.g. 'user', 'max_failures', 'admin'); null when enabled or never disabled.

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/autorecharge/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.11account.autorecharge.configure

PUT /v1/account/autorecharge/configure

配置自动充值:余额低于触发值时自动扣款充值。

Parameters

NameTypeRequiredDescription
trigger_balancenumber
Required
触发余额:钱包余额低于此值即自动充值。
≥ 0
recharge_amountnumber
Required
每次自动充值的金额(美元)。
> 0
payment_method_idstringOptional扣款支付方式 ID,留空则使用账户默认支付方式。
max_per_daynumberOptional每日自动充值次数上限(防滥用)。
≥ 1default: 3
max_per_monthnumberOptional每月自动充值次数上限(防滥用)。
≥ 1default: 30
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

AutorechargeConfig { enabled, trigger_balance, recharge_amount, max_per_day, max_per_month }
NameTypeDescription
enabledbooleanWhether this feature or configuration is enabled
trigger_balancenumberBalance threshold that triggers automatic recharge, in USD
≥ 0
recharge_amountnumberAmount to recharge when triggered, in USD
≥ 0
payment_method_idstringIdentifier of the payment method used
payment_method_summarystringe.g. 'Visa ****4242'.
max_per_dayintegerMaximum recharge amount per day in USD
≥ 1
max_per_monthintegerMaximum recharge amount per month in USD
≥ 1
triggered_todayintegerAmount recharged today in USD
≥ 0
triggered_this_monthintegerAmount recharged this month in USD
≥ 0
next_check_atstring | nullISO 8601 timestamp when the next balance check will occur
format: date-time
last_succeeded_atstring | nullISO 8601 timestamp of the last successful payment
format: date-time
last_failed_atstring | nullISO 8601 timestamp of the last payment failure
format: date-time
consecutive_failuresintegerNumber of consecutive payment failures
≥ 0
configuredbooleanWhether a config row exists for this account (false = never set up; the numeric fields are then zero defaults).
disabled_reasonstring | nullWhy auto-recharge is currently disabled (e.g. 'user', 'max_failures', 'admin'); null when enabled or never disabled.

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X PUT https://api.infrai.cc/v1/account/autorecharge/configure \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trigger_balance": 1.0, "recharge_amount": 1.0}'

2.12account.payment_method.set_default

POST /v1/account/payment_method/set_default

将指定支付方式设为账户默认。

Parameters

NameTypeRequiredDescription
payment_method_idstring
Required
要设为默认的支付方式 ID。
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

AccountPaymentMethod { id, brand, last4, is_default }
NameTypeDescription
payment_method_idstringIdentifier of the payment method used
set_defaultbooleanaccount.payment_method.set_default only. Whether the default was actually changed (false when payment_method_id isn't a known saved method).
status"not_found" | nullaccount.payment_method.set_default only. Present ('not_found') when payment_method_id doesn't match a saved method.
messagestring | nullaccount.payment_method.set_default only. Human-readable detail when set_default is false.
kind"card" | "sepa" | "ach" | "alipay" | "wechat" | "applepay" | "googlepay" | nullOptional. Structured instrument kind; absent for cards saved via the setup-intent flow (only the provider summary is retained) — see `summary`.
summarystring | nullHuman-readable description of the instrument, e.g. 'Visa ****4242'.
stripe_customer_idstring | nullStripe customer id the method is attached to; null in mock/dev.
is_defaultbooleanWhether this is the default payment method
last4string | nullLast 4 digits of the card number
pattern: ^[0-9]{4}$
brandstring | nullCard brand (e.g. visa, mastercard)
expiresstring | nullMM/YY for card kind.
added_atstring | nullISO 8601 timestamp when this resource was added
format: date-time

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/payment_method/set_default \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment_method_id": "sample"}'

2.13account.tier

GET /v1/account/tier

获取当前账户档位及其额度限制。

Returns

TierInfo { tier, limits, billing_period }
NameTypeDescription
tier"standard" | "pro" | "enterprise"Current subscription tier (standard / pro / enterprise)
sincestringISO 8601 date when the current tier or state became effective
format: date-time
wallet_capnumber | nullnull for Enterprise (no cap).
≥ 0
rate_limit_multipliernumberRate limit multiplier applied at this tier
≥ 1
featuresstring[]List of features available at this tier
pro_subscriptionobject | nullDetails of the active Pro subscription, if any
enterprise_contractobject | nullDetails of the enterprise contract, if any
account_idstring | nullThe account whose tier this is.

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/tier \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.14account.subscription.get

GET /v1/account/subscription/get

获取订阅状态(档位、当前周期结束时间、是否将取消)。

Returns

SubscriptionInfo { status, tier, current_period_end, cancel_at_period_end }
NameTypeDescription
model"usage_based"Always usage_based; pay-as-you-go wallet with optional auto-recharge.
tier"standard" | "pro" | "enterprise"Current subscription tier (standard / pro / enterprise)
fixed_subscriptionobject | nullReserved for a future fixed recurring plan; null today (no fixed subscription).
autorechargeobjectThe recurring funding policy: auto top-up of the wallet when it drops below trigger_balance_usd.
autorecharge.enabledboolean-
autorecharge.recharge_amount_usdnumber | null-
≥ 0
autorecharge.trigger_balance_usdnumber | null-
≥ 0
autorecharge.payment_methodstring | nullMasked card summary, e.g. 'Visa ****4242'.

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/subscription/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.15account.keys.create

POST /v1/account/keys/create

创建 API Key,key_secret 仅在创建时返回一次。

Parameters

NameTypeRequiredDescription
namestringOptionalKey 名称(最长 128 字符)。
≤ 128 chars
scopesstring[]Optional作用域列表,留空表示全模块。
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

ApiKey { key_id, name, scopes, key_secret, created_at }
NameTypeDescription
key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
key_secretstring | nullFull plaintext value; returned only on create.
keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
namestring | nullHuman-readable name for this resource
tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
created_atstringISO 8601 timestamp when this resource was created
format: date-time
last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
status"active" | "rotating" | "revoked" | "not_found"Current status of this resource

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/keys/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.16account.keys.update

PATCH /v1/account/keys/update/{id}

更新 API Key 的名称和/或作用域,作用域收紧立即生效。

Parameters

NameTypeRequiredDescription
key_idstring
Required
API Key ID。
namestringOptional新 Key 名称。
≤ 128 chars
scopesstring[]Optional新作用域列表。
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

ApiKey { key_id, name, scopes }
NameTypeDescription
key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
key_secretstring | nullFull plaintext value; returned only on create.
keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
namestring | nullHuman-readable name for this resource
tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
created_atstringISO 8601 timestamp when this resource was created
format: date-time
last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
status"active" | "rotating" | "revoked" | "not_found"Current status of this resource

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X PATCH https://api.infrai.cc/v1/account/keys/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.17account.keys.rotate

POST /v1/account/keys/rotate/{id}

轮换 API Key:签发新密钥,旧密钥在宽限期内仍有效。

Parameters

NameTypeRequiredDescription
key_idstring
Required
API Key ID。
grace_hoursnumberOptional旧密钥宽限有效小时数(0-168,默认 24)。
0–168default: 24
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

ApiKey { key_id, key_secret, status, grace_expires_at }
NameTypeDescription
key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
key_secretstring | nullFull plaintext value; returned only on create.
keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
namestring | nullHuman-readable name for this resource
tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
created_atstringISO 8601 timestamp when this resource was created
format: date-time
last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
status"active" | "rotating" | "revoked" | "not_found"Current status of this resource

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/keys/rotate/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.18account.keys.revoke

DELETE /v1/account/keys/revoke/{id}

吊销 API Key,立即失效。

Parameters

NameTypeRequiredDescription
key_idstring
Required
API Key ID。
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

{ revoked: boolean }
NameTypeDescription
key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
key_secretstring | nullFull plaintext value; returned only on create.
keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
namestring | nullHuman-readable name for this resource
tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
created_atstringISO 8601 timestamp when this resource was created
format: date-time
last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
status"active" | "rotating" | "revoked" | "not_found"Current status of this resource

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X DELETE https://api.infrai.cc/v1/account/keys/revoke/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.19account.keys.suspected_compromise

POST /v1/account/keys/suspected_compromise/{id}

上报 API Key 疑似泄露,可立即吊销并自动签发替换密钥。

Parameters

NameTypeRequiredDescription
key_idstring
Required
API Key ID。
confirmed_leakbooleanOptional是否已确认泄露,true 则立即吊销。
default: false
auto_rotatebooleanOptional是否自动签发替换密钥。
default: true
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

ApiKey { key_id, status, key_secret? }
NameTypeDescription
key_idstringKey id. On list it is MASKED (optional prefix + separator + last 4) — the separator is ASCII '...' (path-safe) or the legacy unicode ellipsis, e.g. ifr_...52fb / ifr_pk_proj_…9180 / ifr_…ab74. The full ifr_ value is only ever returned at create time.
pattern: ^ifr_[A-Za-z0-9_]*(\.\.\.|\u202…
key_secretstring | nullFull plaintext value; returned only on create.
keystring | nullaccount.keys.rotate only. Full plaintext value of the newly-minted secret, shown exactly once (same purpose as key_secret on create, different field name on this endpoint).
old_key_idstring | nullaccount.keys.rotate only. Masked id of the key that was superseded by this rotation.
rotatedbooleanaccount.keys.rotate only. Whether a new secret was actually minted (false when the referenced key was not found).
revokedbooleanaccount.keys.revoke / .suspected_compromise only. Whether the key was actually revoked (false when the referenced key was not found).
actionstring | nullaccount.keys.suspected_compromise only. Fixed action label, e.g. 'revoked_on_compromise_report'.
updatedbooleanaccount.keys.update only. Whether the key record was actually updated (false when the referenced key was not found).
namestring | nullHuman-readable name for this resource
tierstring | nullBilling tier the key inherits from its account (standard/pro/enterprise).
scopesstring[]Granted scopes. OMITTED from list output (internal; session keys filtered) — present only where the surface exposes it.
created_atstringISO 8601 timestamp when this resource was created
format: date-time
last_used_atstring | nullISO 8601 timestamp when this key was last used
format: date-time
last_used_ipstring | nullIP of the most recent request authenticated with this key; null if never used.
expires_atstring | nullISO 8601 timestamp when this resource or token expires
format: date-time
revoked_atstring | nullISO 8601 timestamp when this key was revoked
format: date-time
status"active" | "rotating" | "revoked" | "not_found"Current status of this resource

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/keys/suspected_compromise/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.20account.webhooks.list

GET /v1/account/webhooks/list

分页列出已注册的 Webhook。

Parameters

NameTypeRequiredDescription
cursorstringOptional分页游标:传入上一页返回的 next_cursor 获取下一页。
limitnumberOptional单页返回条数上限。

Returns

{ items: Array<Webhook>, next_cursor? }
NameTypeDescription
itemsobject[]Array of result items in this page
items[].webhook_idstringWebhook subscription id (whk_… in the account_resource store).
pattern: ^whk?_[A-Za-z0-9]{16,}$
items[].urlstringURL for this resource or endpoint
format: uri
items[].eventsstring[]Event names per enums/webhook_event.yaml.
items[].descriptionstring | nullFree-text description of this resource
items[].secretstring | nullPlaintext secret — returned only on initial create.
items[].secret_hashstring | nullSHA-256 hex of secret; returned on list/get.
items[].activebooleanWhether deliveries are sent. Canonical state field.
items[].enabledboolean | nullBack-compat alias of `active` (console reads this).
items[].statusstring | nullaccount_resource lifecycle status (e.g. 'active').
items[].retry_policy"default" | "aggressive" | nullRetry policy configuration
items[].headersobject | nullCustom HTTP headers added to every delivery.
items[].last_delivery_atstring | nullISO 8601 timestamp of the last delivery attempt
format: date-time
items[].last_delivery_status"success" | "failed" | nullStatus of the last delivery attempt
items[].failure_count_24hintegerNumber of failed deliveries in the last 24 hours
≥ 0
items[].auto_disabled_atstring | nullSet when 100 consecutive failures triggered auto-disable.
format: date-time
items[].created_atstring | nullISO 8601 timestamp when this resource was created. Absent on account.webhooks.update (patch response echoes updated_at only).
format: date-time
items[].updated_atstring | nullISO 8601 timestamp when this resource was last updated. Returned by .get/.update; absent on .register/.list.
format: date-time
next_cursorstring | nullOpaque cursor to fetch the next page; null/absent if this is the last page
countintegerTotal number of items across all pages
≥ 0

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/webhooks/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.21account.webhooks.register

POST /v1/account/webhooks/register

注册 Webhook,URL 须为公网 https 端点(服务端做 SSRF 校验),secret 仅返回一次。

Parameters

NameTypeRequiredDescription
urlstring
Required
接收回调的公网 https 地址。
format: uri
events("account.created" | "account.updated" | "account.absorbed" | "account.device_linked" | "account.deleted" | "topup.succeeded" | "topup.failed" | "topup.review_started" | "autorecharge.charged" | "autorecharge.failed" | "subscription.activated" | "subscription.renewed" | "subscription.cancelled" | "kyc.status_changed" | "tier.upgraded" | "tier.downgraded" | "wallet.low_balance" | "wallet.expiring_soon" | "wallet.expired" | "email.queued" | "email.sent" | "email.delivered" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.deferred" | "email.cancelled" | "email.unsubscribed" | "email.auto_suppressed" | "sms.queued" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.inbound" | "image.job.completed" | "image.job.failed" | "video.job.completed" | "video.job.failed" | "ai.batch.completed" | "ai.batch.failed" | "captcha.verified" | "captcha.failed" | "realtime.channel.occupied" | "realtime.channel.vacated" | "realtime.member.added" | "realtime.member.removed" | "cron.executed" | "cron.failed" | "queue.dlq" | "error.captured" | "error.rate_anomaly" | "system.vendor.down" | "system.maintenance.scheduled")[]
Required
订阅的事件类型列表。
≥ 1 item
descriptionstringOptional备注说明(可选,最长 256 字符)。
≤ 256 chars
secretstringOptional自定义签名密钥,留空则自动生成。
retry_policy"default" | "aggressive" | nullOptional重试策略:default 或 aggressive。
headersRecord<string, string>Optional每次投递附加的自定义 HTTP 头。
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

Webhook { id, url, events, secret, active }
NameTypeDescription
webhook_idstringWebhook subscription id (whk_… in the account_resource store).
pattern: ^whk?_[A-Za-z0-9]{16,}$
urlstringURL for this resource or endpoint
format: uri
eventsstring[]Event names per enums/webhook_event.yaml.
descriptionstring | nullFree-text description of this resource
secretstring | nullPlaintext secret — returned only on initial create.
secret_hashstring | nullSHA-256 hex of secret; returned on list/get.
activebooleanWhether deliveries are sent. Canonical state field.
enabledboolean | nullBack-compat alias of `active` (console reads this).
statusstring | nullaccount_resource lifecycle status (e.g. 'active').
retry_policy"default" | "aggressive" | nullRetry policy configuration
headersobject | nullCustom HTTP headers added to every delivery.
last_delivery_atstring | nullISO 8601 timestamp of the last delivery attempt
format: date-time
last_delivery_status"success" | "failed" | nullStatus of the last delivery attempt
failure_count_24hintegerNumber of failed deliveries in the last 24 hours
≥ 0
auto_disabled_atstring | nullSet when 100 consecutive failures triggered auto-disable.
format: date-time
created_atstring | nullISO 8601 timestamp when this resource was created
format: date-time
updated_atstring | nullISO 8601 timestamp when this resource was last updated. Returned by .get/.update; absent on .register/.list.
format: date-time

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/webhooks/register \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/callback", "events": ["account.created"]}'

2.22account.webhooks.get

GET /v1/account/webhooks/get/{id}

获取单个 Webhook 详情。

Parameters

NameTypeRequiredDescription
webhook_idstring
Required
Webhook ID。

Returns

Webhook { id, url, events, active, retry_policy }
NameTypeDescription
webhook_idstringWebhook subscription id (whk_… in the account_resource store).
pattern: ^whk?_[A-Za-z0-9]{16,}$
urlstringURL for this resource or endpoint
format: uri
eventsstring[]Event names per enums/webhook_event.yaml.
descriptionstring | nullFree-text description of this resource
secretstring | nullPlaintext secret — returned only on initial create.
secret_hashstring | nullSHA-256 hex of secret; returned on list/get.
activebooleanWhether deliveries are sent. Canonical state field.
enabledboolean | nullBack-compat alias of `active` (console reads this).
statusstring | nullaccount_resource lifecycle status (e.g. 'active').
retry_policy"default" | "aggressive" | nullRetry policy configuration
headersobject | nullCustom HTTP headers added to every delivery.
last_delivery_atstring | nullISO 8601 timestamp of the last delivery attempt
format: date-time
last_delivery_status"success" | "failed" | nullStatus of the last delivery attempt
failure_count_24hintegerNumber of failed deliveries in the last 24 hours
≥ 0
auto_disabled_atstring | nullSet when 100 consecutive failures triggered auto-disable.
format: date-time
created_atstring | nullISO 8601 timestamp when this resource was created
format: date-time
updated_atstring | nullISO 8601 timestamp when this resource was last updated. Returned by .get/.update; absent on .register/.list.
format: date-time

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/webhooks/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.23account.webhooks.update

PATCH /v1/account/webhooks/update/{id}

局部更新 Webhook,修改 URL 会重新触发 SSRF 校验。

Parameters

NameTypeRequiredDescription
webhook_idstring
Required
Webhook ID。
urlstringOptional新的公网 https 地址。
format: uri
events("account.created" | "account.updated" | "account.absorbed" | "account.device_linked" | "account.deleted" | "topup.succeeded" | "topup.failed" | "topup.review_started" | "autorecharge.charged" | "autorecharge.failed" | "subscription.activated" | "subscription.renewed" | "subscription.cancelled" | "kyc.status_changed" | "tier.upgraded" | "tier.downgraded" | "wallet.low_balance" | "wallet.expiring_soon" | "wallet.expired" | "email.queued" | "email.sent" | "email.delivered" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.deferred" | "email.cancelled" | "email.unsubscribed" | "email.auto_suppressed" | "sms.queued" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.inbound" | "image.job.completed" | "image.job.failed" | "video.job.completed" | "video.job.failed" | "ai.batch.completed" | "ai.batch.failed" | "captcha.verified" | "captcha.failed" | "realtime.channel.occupied" | "realtime.channel.vacated" | "realtime.member.added" | "realtime.member.removed" | "cron.executed" | "cron.failed" | "queue.dlq" | "error.captured" | "error.rate_anomaly" | "system.vendor.down" | "system.maintenance.scheduled")[] | nullOptional新的订阅事件类型列表。
≥ 1 item
descriptionstringOptional备注说明。
≤ 256 chars
activebooleanOptional是否启用该 Webhook。
retry_policy"default" | "aggressive" | nullOptional重试策略:default 或 aggressive。
headersRecord<string, string>Optional每次投递附加的自定义 HTTP 头。
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

Webhook { id, url, events, active, retry_policy }
NameTypeDescription
webhook_idstringWebhook subscription id (whk_… in the account_resource store).
pattern: ^whk?_[A-Za-z0-9]{16,}$
urlstringURL for this resource or endpoint
format: uri
eventsstring[]Event names per enums/webhook_event.yaml.
descriptionstring | nullFree-text description of this resource
secretstring | nullPlaintext secret — returned only on initial create.
secret_hashstring | nullSHA-256 hex of secret; returned on list/get.
activebooleanWhether deliveries are sent. Canonical state field.
enabledboolean | nullBack-compat alias of `active` (console reads this).
statusstring | nullaccount_resource lifecycle status (e.g. 'active').
retry_policy"default" | "aggressive" | nullRetry policy configuration
headersobject | nullCustom HTTP headers added to every delivery.
last_delivery_atstring | nullISO 8601 timestamp of the last delivery attempt
format: date-time
last_delivery_status"success" | "failed" | nullStatus of the last delivery attempt
failure_count_24hintegerNumber of failed deliveries in the last 24 hours
≥ 0
auto_disabled_atstring | nullSet when 100 consecutive failures triggered auto-disable.
format: date-time
created_atstring | nullISO 8601 timestamp when this resource was created
format: date-time
updated_atstring | nullISO 8601 timestamp when this resource was last updated. Returned by .get/.update; absent on .register/.list.
format: date-time

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X PATCH https://api.infrai.cc/v1/account/webhooks/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.24account.webhooks.delete

DELETE /v1/account/webhooks/delete/{id}

删除 Webhook。

Parameters

NameTypeRequiredDescription
webhook_idstring
Required
Webhook ID。
idempotency_keystringOptionalOptional dedup key; identical retries return the same result.

Returns

{ deleted: boolean }
NameTypeDescription
webhook_idstringThe webhook id that was targeted for deletion.
deletedbooleanWhether a webhook was actually deleted (false when webhook_id didn't resolve to a row on this account).

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X DELETE https://api.infrai.cc/v1/account/webhooks/delete/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.25account.webhooks.test

POST /v1/account/webhooks/test/{id}

向 Webhook 发送一条测试事件以验证连通性。

Parameters

NameTypeRequiredDescription
webhook_idstring
Required
Webhook ID。

Returns

WebhookDelivery { delivery_id, status_code, ok }
NameTypeDescription
webhook_idstringUnique identifier for this webhook
pattern: ^wh_[A-Za-z0-9]{20,}$
eventstringEvent name fired in the test (e.g. 'topup.succeeded').
deliveredbooleanWhether the webhook delivery succeeded
http_statusinteger | nullHTTP status code of the webhook delivery attempt
100–599
latency_msinteger | nullLatency of the operation in milliseconds
≥ 0
errorstring | nullError message if the operation failed
delivery_idstring | nullUnique identifier for this delivery attempt
pattern: ^dlv_[A-Za-z0-9]{20,}$
tested_atstringISO 8601 timestamp when the test was executed
format: date-time

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/webhooks/test/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

2.26account.webhooks.deliveries

GET /v1/account/webhooks/deliveries/{id}

分页列出某 Webhook 的投递记录。

Parameters

NameTypeRequiredDescription
webhook_idstring
Required
Webhook ID。
cursorstringOptional分页游标:传入上一页返回的 next_cursor 获取下一页。
limitnumberOptional单页返回条数上限。

Returns

{ items: Array<WebhookDelivery>, next_cursor? }
NameTypeDescription
itemsobject[]Array of result items in this page
items[].delivery_idstringUnique identifier for this delivery attempt
pattern: ^dlv_[A-Za-z0-9]{20,}$
items[].webhook_idstringUnique identifier for this webhook
pattern: ^wh_[A-Za-z0-9]{20,}$
items[].eventstringEvent name per enums/webhook_event.yaml.
items[].status"pending" | "success" | "retry" | "failed" | "dlq"Current status of this resource
items[].attemptintegerCurrent attempt number (for retries)
≥ 1
items[].http_statusinteger | nullHTTP status code of the webhook delivery attempt
100–599
items[].latency_msinteger | nullLatency of the operation in milliseconds
≥ 0
items[].response_body_truncatedstring | nullTruncated response body from the webhook delivery attempt
≤ 4096 chars
items[].errorstring | nullError message if the operation failed
items[].created_atstringISO 8601 timestamp when this resource was created
format: date-time
items[].completed_atstring | nullISO 8601 timestamp when execution completed
format: date-time
next_cursorstring | nullOpaque cursor to fetch the next page; null/absent if this is the last page
countintegerTotal number of items across all pages
≥ 0

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/webhooks/deliveries/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.27account.routing.get

GET /v1/account/routing/get

获取账户级路由配置(链路覆盖、故障转移策略、固定厂商)。

Returns

RoutingConfig { chain_override?, failover_policy, pinned_vendors }
NameTypeDescription
preferencesobjectaccount.routing.get only. Per-capability vendor exclude list the account has configured, keyed by capability id.
effective_chainsobjectaccount.routing.get only. Per-capability failover chain after applying the account's exclude and filtering to currently-usable vendors, keyed by capability id. Each entry is model-first: the vendor plus the model it serves.
no_china_routebooleanaccount.routing.get (current value) / account.routing.set (echoed new value, only when the no_china_route toggle was set). Data-sovereignty flag: when true the gateway routes only to non-China vendors.
capabilitystringaccount.routing.set only (per-capability exclude sub-action). The capability the exclude list was set for.
excludestring[]account.routing.set only (per-capability exclude sub-action). Echo of the vendor ids excluded from that capability's chain.
okbooleanaccount.routing.set only. Always true — confirms the write was applied.

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X GET https://api.infrai.cc/v1/account/routing/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

2.28account.routing.set

PUT /v1/account/routing/set

设置账户级路由:覆盖默认厂商链路、固定指定厂商。

Parameters

NameTypeRequiredDescription
chain_overridestring[]Optional厂商优先级链路覆盖列表。
pinned_vendorsstring[]Optional固定使用的厂商列表。

Returns

RoutingConfig { chain_override?, failover_policy, pinned_vendors }
NameTypeDescription
preferencesobjectaccount.routing.get only. Per-capability vendor exclude list the account has configured, keyed by capability id.
effective_chainsobjectaccount.routing.get only. Per-capability failover chain after applying the account's exclude and filtering to currently-usable vendors, keyed by capability id. Each entry is model-first: the vendor plus the model it serves.
no_china_routebooleanaccount.routing.get (current value) / account.routing.set (echoed new value, only when the no_china_route toggle was set). Data-sovereignty flag: when true the gateway routes only to non-China vendors.
capabilitystringaccount.routing.set only (per-capability exclude sub-action). The capability the exclude list was set for.
excludestring[]account.routing.set only (per-capability exclude sub-action). Echo of the vendor ids excluded from that capability's chain.
okbooleanaccount.routing.set only. Always true — confirms the write was applied.

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X PUT https://api.infrai.cc/v1/account/routing/set \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"capability": "ai.chat"}'

2.29account.routing.test

POST /v1/account/routing/test

测试路由解析:给定能力返回将选用的厂商链路。

Parameters

NameTypeRequiredDescription
capabilitystring
Required
要测试的能力 ID(如 ai.chat)。
default: "ai.chat"e.g. ai.chat
chain_overridestring[]Optional用于本次测试的临时链路覆盖。

Returns

RoutingTestResult { ok, resolved_vendor, resolved_model?, tested_at? }
NameTypeDescription
capabilitystringThe capability that was tested (defaults to ai.chat if not given).
customizablebooleanWhether this capability accepts a per-account vendor exclude (AI-inference/stateless only).
chainstring[]The effective vendor id chain after applying the account's exclude and filtering to currently-usable vendors.
resultsobject[]Per-vendor reachability, one entry per vendor in `chain`.
results[].vendorstring-
results[].modelstring | nullThe model this vendor would serve for the capability, best-effort.
results[].upbooleanWhether the vendor is currently marked up in the live registry.
okbooleanWhether the test routing resolved successfully

Example

一次性前置(每个范例都假定已完成):

bash
# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at https://infrai.cc/login (Google/GitHub gives
# you $2 free credit; email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT, add
# funds at https://infrai.cc/billing (or POST /v1/account/topup and open the
# returned checkout_url).
export INFRAI_API_KEY="ifr_..."
bash
curl -X POST https://api.infrai.cc/v1/account/routing/test \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

3. All capabilities

Every routed capability in this module — the complete public REST contract. The methods above are the guided walkthrough; this index is the full reference.

account.autorecharge.configurePUT /v1/account/autorecharge/configure

Configure automatic balance top-up when funds fall below a trigger threshold, with anti-abuse caps.

Parameters (6)
NameTypeRequiredDescription
trigger_balancenumberRequiredAuto-charge fires when wallet balance drops below this.
≥ 0
recharge_amountnumberRequiredAmount in USD to add each time auto-charge fires.
> 0
payment_method_idstring | nullOptionalnull uses the account default payment method.
max_per_dayintegerOptionalMaximum recharge amount per day in USD
≥ 1default: 3
max_per_monthintegerOptionalMaximum recharge amount per month in USD
≥ 1default: 30
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.autorecharge.getGET /v1/account/autorecharge/get

Get the current auto-recharge configuration.

No request parameters.

account.balanceGET /v1/account/balance

Get the account wallet balance and trial status.

No request parameters.

account.budget.getGET /v1/account/budget/get

Get the budget configuration (period, hard cap, alert thresholds).

No request parameters.

account.budget.setPUT /v1/account/budget/set

Set a hard budget cap and alert thresholds, blocking billable calls when exceeded.

Parameters (4)
NameTypeRequiredDescription
hard_cap_usdnumber | nullOptionalMonthly spending hard cap in USD
≥ 0
period"daily" | "monthly"RequiredBilling or retention period (e.g. monthly, daily)
alert_threshold_usdnumber | nullOptionalMonthly spending alert threshold in USD
≥ 0
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.keys.createPOST /v1/account/keys/create

Create an API key; the secret is returned only once.

Parameters (4)
NameTypeRequiredDescription
project_idstring | nullOptionalnull = caller's current project.
namestring | nullOptionalHuman-readable name for this resource
≤ 128 chars
scopesstring[] | nullOptionalEmpty/null = all-modules; explicit scopes per enums/key_scope.yaml.
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.keys.listGET /v1/account/keys/list

List all API keys on the account and their status.

No request parameters.

account.keys.revokeDELETE /v1/account/keys/revoke/{id}

Revoke an API key, taking effect immediately.

Parameters (1)
NameTypeRequiredDescription
idstringRequiredPath parameter.
account.keys.rotatePOST /v1/account/keys/rotate/{id}

Rotate an API key; the old secret stays valid during a grace period.

Parameters (3)
NameTypeRequiredDescription
idstringRequiredPath parameter.
grace_hoursintegerOptionalHours the old key remains valid after rotation
0–168default: 24
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.keys.suspected_compromisePOST /v1/account/keys/suspected_compromise/{id}

Report an API key as suspected compromised to immediately revoke and auto-reissue it.

Parameters (4)
NameTypeRequiredDescription
idstringRequiredPath parameter.
confirmed_leakbooleanOptionalWhether the key leak has been confirmed
default: false
auto_rotatebooleanOptionalWhether to automatically rotate the compromised key
default: true
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.keys.updatePATCH /v1/account/keys/update/{id}

Update an API key's name or scopes; scope tightening takes effect immediately.

Parameters (4)
NameTypeRequiredDescription
idstringRequiredPath parameter.
namestring | nullOptionalHuman-readable name for this resource
≤ 128 chars
scopesstring[] | nullOptionalPermission scopes granted to this API key
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.payment_method.set_defaultPOST /v1/account/payment_method/set_default

Set a payment method as the account default.

Parameters (2)
NameTypeRequiredDescription
payment_method_idstringRequiredIdentifier of the payment method used
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.routing.getGET /v1/account/routing/get

Get the account's AI routing preference: per-capability vendor chains (model-annotated) + excluded vendors.

No request parameters.

account.routing.setPUT /v1/account/routing/set

Exclude vendors from an AI capability's routing (cost / reliability / data sovereignty).

Parameters (3)
NameTypeRequiredDescription
capabilitystringRequiredAI-inference capability id (ai.*) whose vendor exclude is being set.
e.g. ai.chat
excludestring[]OptionalVendors to never route this capability to (cost / reliability / data sovereignty).
default: []e.g. ["openai"]
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.routing.testPOST /v1/account/routing/test

Test routing resolution for an AI capability: the vendor chain and the model each serves.

Parameters (1)
NameTypeRequiredDescription
capabilitystring | nullOptionalCapability id whose routing chain to test (defaults to ai.chat).
default: "ai.chat"e.g. ai.chat
account.subscription.getGET /v1/account/subscription/get

Get the subscription status and billing period.

No request parameters.

account.tierGET /v1/account/tier

Get the current tier and its quota limits.

No request parameters.

account.tier.upgradePOST /v1/account/tier/upgrade

Upgrade the account tier (pro/team/enterprise), returning a checkout URL when payment is required.

Parameters (3)
NameTypeRequiredDescription
target"pro" | "team" | "enterprise"RequiredTarget URL or resource for webhook or notification
return_urlstring | nullOptionalWhere checkout redirects after success/cancel; echoed into the hosted checkout session.
format: uri
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.topupPOST /v1/account/topup

Create a Stripe top-up session and return the hosted payment page URL.

Parameters (5)
NameTypeRequiredDescription
amount_usdnumber | nullOptionalTop-up amount in USD.
≥ 0
amountnumber | nullOptionalLegacy alias for amount_usd.
≥ 0
currencystringOptionalISO 4217 currency code (e.g. USD, CNY)
default: "USD"
return_urlstring | nullOptionalURL the checkout redirects back to; defaults to the configured return URL.
format: uri
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.usageGET /v1/account/usage

Summarize usage for the current billing period: spend, request count, and a per-capability breakdown.

No request parameters.

account.usage.timeseriesGET /v1/account/usage/timeseries

Return a usage time series at hour, day, or month granularity.

No request parameters.

account.webhooks.deleteDELETE /v1/account/webhooks/delete/{id}

Delete a webhook registration; no further event deliveries are sent to its URL. Idempotent.

Parameters (1)
NameTypeRequiredDescription
idstringRequiredPath parameter.
account.webhooks.deliveriesGET /v1/account/webhooks/deliveries/{id}

List a webhook's delivery records with pagination.

Parameters (1)
NameTypeRequiredDescription
idstringRequiredPath parameter.
account.webhooks.getGET /v1/account/webhooks/get/{id}

Get details for a single webhook.

Parameters (1)
NameTypeRequiredDescription
idstringRequiredPath parameter.
account.webhooks.listGET /v1/account/webhooks/list

List registered webhooks with pagination.

No request parameters.

account.webhooks.registerPOST /v1/account/webhooks/register

Register a webhook (public HTTPS, SSRF-validated); the signing secret is returned only once.

Parameters (7)
NameTypeRequiredDescription
urlstringRequiredURL for this resource or endpoint
format: uri
events("account.created" | "account.updated" | "account.absorbed" | "account.device_linked" | "account.deleted" | "topup.succeeded" | "topup.failed" | "topup.review_started" | "autorecharge.charged" | "autorecharge.failed" | "subscription.activated" | "subscription.renewed" | "subscription.cancelled" | "kyc.status_changed" | "tier.upgraded" | "tier.downgraded" | "wallet.low_balance" | "wallet.expiring_soon" | "wallet.expired" | "email.queued" | "email.sent" | "email.delivered" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.deferred" | "email.cancelled" | "email.unsubscribed" | "email.auto_suppressed" | "sms.queued" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.inbound" | "image.job.completed" | "image.job.failed" | "video.job.completed" | "video.job.failed" | "ai.batch.completed" | "ai.batch.failed" | "captcha.verified" | "captcha.failed" | "realtime.channel.occupied" | "realtime.channel.vacated" | "realtime.member.added" | "realtime.member.removed" | "cron.executed" | "cron.failed" | "queue.dlq" | "error.captured" | "error.rate_anomaly" | "system.vendor.down" | "system.maintenance.scheduled")[]RequiredEvent types to subscribe this webhook to; the closed set is the global event catalog.
≥ 1 item
descriptionstring | nullOptionalFree-text description of this resource
≤ 256 chars
secretstring | nullOptionalOptional caller-provided signing secret; auto-generated when null.
retry_policy"default" | "aggressive" | nullOptionalRetry policy configuration
headersobject | nullOptionalCustom HTTP headers added to every delivery.
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.webhooks.testPOST /v1/account/webhooks/test/{id}

Send a test event to a webhook to verify connectivity.

Parameters (1)
NameTypeRequiredDescription
idstringRequiredPath parameter.
account.webhooks.updatePATCH /v1/account/webhooks/update/{id}

Partially update a webhook; changing the URL re-runs SSRF validation.

Parameters (8)
NameTypeRequiredDescription
idstringRequiredPath parameter.
urlstring | nullOptionalURL for this resource or endpoint
format: uri
events("account.created" | "account.updated" | "account.absorbed" | "account.device_linked" | "account.deleted" | "topup.succeeded" | "topup.failed" | "topup.review_started" | "autorecharge.charged" | "autorecharge.failed" | "subscription.activated" | "subscription.renewed" | "subscription.cancelled" | "kyc.status_changed" | "tier.upgraded" | "tier.downgraded" | "wallet.low_balance" | "wallet.expiring_soon" | "wallet.expired" | "email.queued" | "email.sent" | "email.delivered" | "email.opened" | "email.clicked" | "email.bounced" | "email.complained" | "email.deferred" | "email.cancelled" | "email.unsubscribed" | "email.auto_suppressed" | "sms.queued" | "sms.sent" | "sms.delivered" | "sms.failed" | "sms.inbound" | "image.job.completed" | "image.job.failed" | "video.job.completed" | "video.job.failed" | "ai.batch.completed" | "ai.batch.failed" | "captcha.verified" | "captcha.failed" | "realtime.channel.occupied" | "realtime.channel.vacated" | "realtime.member.added" | "realtime.member.removed" | "cron.executed" | "cron.failed" | "queue.dlq" | "error.captured" | "error.rate_anomaly" | "system.vendor.down" | "system.maintenance.scheduled")[] | nullOptionalList of event types this subscription listens to
≥ 1 item
descriptionstring | nullOptionalFree-text description of this resource
≤ 256 chars
activeboolean | nullOptionalWhether this resource is currently active
retry_policy"default" | "aggressive" | nullOptionalRetry policy configuration
headersobject | nullOptionalCustom HTTP headers to include in requests or responses
idempotency_keystring | nullOptionalClient-provided idempotency key; prevents duplicate execution on retry
account.whoamiGET /v1/account/whoami

Get an account summary (ID, type, status, tier, balance).

No request parameters.

4. End-to-end example

A production-style walkthrough of this module: configure once, then run the flow. It exercises most of the module's APIs.

A copy-paste-runnable single-file Python program (stdlib only, no SDK): set your INFRAI_API_KEY, run it, and walk this module's core flow with REAL billed calls — later steps reuse real fields returned by earlier ones. The 12-line helper is the entire integration.

python
#!/usr/bin/env python3
"""Infrai · account — runnable real-app example (single file, zero deps).

Copy this file, set your key, run it: every step is a REAL call to
api.infrai.cc, billed at the real (tiny) per-call price, printing the
live JSON response. Get a key at https://infrai.cc/login (Google/
GitHub sign-in grants $2 free credit); add funds at
https://infrai.cc/billing. No SDK — the 12-line helper below is the
entire integration."""
import json
import os
from urllib import error, request

KEY = os.environ.get("INFRAI_API_KEY") or "ifr_..."  # <- your key
BASE = "https://api.infrai.cc"


# Same raw HTTPS POST/GET as every per-method example on this page —
# wrapped once for reuse. There is nothing else to it: no SDK.
def infrai(method, path, body=None):
    req = request.Request(
        BASE + path, method=method,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": f"Bearer {KEY}",
                 "Content-Type": "application/json"})
    try:
        with request.urlopen(req, timeout=60) as r:
            return json.loads(r.read())
    except error.HTTPError as e:
        return json.loads(e.read())


def show(label, resp):
    print(f"\n== {label} ==")
    print(json.dumps(resp, indent=2, ensure_ascii=False))
    return resp


# 1) account.whoami — GET /v1/account/whoami · Get an account summary (ID, type, status, tier, balance).
r1 = show("account.whoami", infrai("GET", "/v1/account/whoami"))

# 2) account.balance — GET /v1/account/balance · Get the account wallet balance and trial status.
r2 = show("account.balance", infrai("GET", "/v1/account/balance"))

# 3) account.usage — GET /v1/account/usage · Summarize usage for the current billing period: spend, request count, and a per-capability breakdown.
r3 = show("account.usage", infrai("GET", "/v1/account/usage"))