Management API

计费管理

GET /v1/billing/teams/{team_id}/billing-info

获取指定团队ID的计费信息。

路径参数

team_id (string, required) — 团队的团队ID。

响应体

billingInfo (object) — 计费信息。
- name (string) — 客户的全名或商业名称。
- address (object) — 计费地址。
  - line1 (string) — 地址行1（例如：街道、邮政信箱或公司名称）。
  - line2 (string) — 地址行2（例如：公寓、套房、单元或建筑物）。
  - city (string) — 城市、地区、郊区、城镇或村庄。
  - country (string) — 两位字母的国家代码（ISO 3166-1 alpha-2）。
  - postalCode (string) — ZIP或邮政编码。
  - state (string) — 州、县、省或地区。
- email (string) — 客户的电子邮件。
- taxIdType (string)
- taxNumber (string)

**响应示例：**

json

{
  "billingInfo": {
    "name": "Acme Inc.",
    "address": {
      "line1": "123 Main St.",
      "line2": "",
      "city": "New York",
      "country": "US",
      "postalCode": "12345",
      "state": "New York"
    },
    "email": "foo@example.com",
    "taxIdType": "us_ein",
    "taxNumber": "12-3456789"
  }
}

POST /v1/billing/teams/{team_id}/billing-info

设置团队的计费信息。

路径参数

team_id (string, required) — 团队的团队ID。

请求体

billingInfo (object) — 计费信息。
- name (string) — 客户的全名或商业名称。
- address (object) — 计费地址。
  - line1 (string) — 地址行1（例如：街道、邮政信箱或公司名称）。
  - line2 (string) — 地址行2（例如：公寓、套房、单元或建筑物）。
  - city (string) — 城市、地区、郊区、城镇或村庄。
  - country (string) — 两位字母的国家代码（ISO 3166-1 alpha-2）。
  - postalCode (string) — ZIP或邮政编码。
  - state (string) — 州、县、省或地区。
- email (string) — 客户的电子邮件。
- taxIdType (string)
- taxNumber (string)

**请求示例：**

json

{
  "billingInfo": {
    "name": "Acme Inc.",
    "address": {
      "line1": "123 Main St.",
      "line2": "",
      "city": "New York",
      "country": "US",
      "postalCode": "12345",
      "state": "New York"
    },
    "email": "foo@example.com",
    "taxIdType": "us_ein",
    "taxNumber": "12-3456789"
  }
}

**响应示例：**

json

{}

GET /v1/billing/teams/{team_id}/invoices

列出属于团队的发票。

路径参数

team_id (string, required) — 团队的团队ID。

查询参数

billingCycle.year (integer)
billingCycle.month (integer)
since.year (integer)
since.month (integer)
invoiceIds.invoiceIds (array<string>)

响应体

invoices (array<object>) — 发票。
- teamId (string) — 团队ID。
- invoiceId (string) — 发票ID。
- invoiceNumber (string) — 发票编号。
- createTime (string) — 发票的创建时间。
- invoiceStatus ("INVALID" | "PENDING" | "PAID" | "WILL_NEVER_BE_CHARGED" | "FAILED") — 发票的收费状态。
- firstDesiredNextCycleTs (string) — 预计向客户收费的时间。
- chargerAttempts (array<object>)
  - ticket (integer)
  - successful (boolean)
  - paymentMethodId (string) — 此尝试中使用的支付方式。
- lines (array<object>) — 组成发票的项目列表。
  - clusterName (string) — 消耗资源的集群。
  - description (string) — 行项目的描述。
  - unitType (string) — 价格测量的单位。
  - unitPrice (string) — 每单位的价格（1/1_000_000美元美分）。
  - numUnits (string) — 单位数。
  - amount (string) — 行项目的总金额（美元美分）。
- subtotal (string)
- tax (string) — 不含税的金额（美元美分）。
- total (string) — 发票总金额（含税）（美元美分）。
- invoicePdfAssetKeySuffix (string) — 发票pdf后缀。
- monthly (object)
  - billingCycle (object)
    - year (integer)
    - month (integer)
  - defaultCreditsIssued (object) — 美元美分的表示。
    - val (string)
  - autoCreditsIssued (object) — 美元美分的表示。
    - val (string)
  - prepaidTokensToSpend (object) — 美元美分的表示。
    - val (string)
  - billingItemsCsvAssetKeySuffix (string) — 计费项目csv文件后缀，由xAI进程使用。
  - correctionsCsvAssetKeySuffix (string) — 计费项目修正csv文件后缀，由xAI进程使用。
- prepaid (object)
- subscriptions (object)

**响应示例：**

json

{
  "invoices": [
    {
      "teamId": "65c1e471-205f-4566-9c5a-07198bcdf4ce",
      "invoiceId": "aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=",
      "invoiceNumber": "742-250-927-721",
      "createTime": "2025-04-01T21:19:48.569466Z",
      "invoiceStatus": "PAID",
      "firstDesiredNextCycleTs": "2025-04-11T02:46:58Z",
      "chargerAttempts": [
        {
          "ticket": 0,
          "successful": false,
          "paymentMethodId": ""
        },
        {
          "ticket": 1,
          "successful": true,
          "paymentMethodId": ""
        }
      ],
      "lines": [
        {
          "clusterName": "us-east-1",
          "description": "Chat grok-2-1212-1.0.0",
          "unitType": "Prompt text tokens",
          "unitPrice": "20000",
          "numUnits": "908",
          "amount": "0"
        },
        {
          "clusterName": "us-east-1",
          "description": "Chat grok-2-1212-1.0.0",
          "unitType": "Completion text tokens",
          "unitPrice": "100000",
          "numUnits": "534",
          "amount": "0"
        }
      ],
      "subtotal": "0",
      "tax": "0",
      "total": "0",
      "invoicePdfAssetKeySuffix": "teams/65c1e471-205f-4566-9c5a-07198bcdf4ce/billing/2025-2-aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=.pdf",
      "monthly": {
        "billingCycle": {
          "year": 2025,
          "month": 2
        },
        "defaultCreditsIssued": {
          "val": "0"
        },
        "autoCreditsIssued": {
          "val": "0"
        },
        "prepaidTokensToSpend": {
          "val": "0"
        },
        "billingItemsCsvAssetKeySuffix": "teams/65c1e471-205f-4566-9c5a-07198bcdf4ce/billing/2025-2-aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=-billing_items.csv.zstd",
        "correctionsCsvAssetKeySuffix": "teams/65c1e471-205f-4566-9c5a-07198bcdf4ce/billing/2025-2-aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=-corrections.csv.zstd"
      }
    }
  ]
}

GET /v1/billing/teams/{team_id}/payment-method

列出团队的支付方式。您可以在 https://console.x.ai 上添加或删除支付方式。

路径参数

team_id (string, required) — 团队的团队ID。

响应体

paymentMethods (array<object>) — 存档的支付方式。
- paymentMethodId (string)
- billingInfo (object) — 计费信息。
  - name (string) — 客户的全名或商业名称。
  - address (object) — 计费地址。
    - line1 (string) — 地址行1（例如：街道、邮政信箱或公司名称）。
    - line2 (string) — 地址行2（例如：公寓、套房、单元或建筑物）。
    - city (string) — 城市、地区、郊区、城镇或村庄。
    - country (string) — 两位字母的国家代码（ISO 3166-1 alpha-2）。
    - postalCode (string) — ZIP或邮政编码。
    - state (string) — 州、县、省或地区。
  - email (string) — 客户的电子邮件。
  - taxIdType (string)
  - taxNumber (string)
- cardDetails (object) — 卡片详情的编辑版本。实际的卡片详情由第三方支付提供商处理。
  - brand (string) — 卡品牌。可以是 `amex`、`diners`、`discover`、`eftpos_au`、`jcb`、`mastercard`、`unionpay`、`visa` 或 `unknown`。
  - expMonth (string) — 代表卡片到期月份的两位数字。
  - expYear (string) — 代表卡片到期年份的四位数字。
  - last4 (string) — 卡片的最后四位数字。
- usBankAccountDetails (object) — ACH详情。
  - bankName (string)
  - last4 (string)
  - routingNumber (string)
  - blocked (object) — ACH阻塞原因。
    - networkCode (string)
    - blockReason (string)
- linkDetails (object) — 链接支付详情。
  - email (string)
- paymentType (string)
- addedTs (string)
pendingPaymentMethod (object) — 表示添加支付方式的未完成尝试。可能会解析为支付方式。
- achMicrodepositHostedVerificationUrl (string) — 用于验证账户的ACH微存款验证URL。

**响应示例：**

json

{
  "paymentMethods": [
    {
      "paymentMethodId": "pm_xxxxxxxxxxxxxxxxxxxxxxxx",
      "billingInfo": {
        "name": "Acme Inc.",
        "address": {
          "line1": "123 Main St.",
          "line2": "",
          "city": "New York",
          "country": "US",
          "postalCode": "12345",
          "state": "New York"
        },
        "email": "foo@example.com",
        "taxIdType": "us-ein",
        "taxNumber": "123-3456789"
      },
      "cardDetails": {
        "brand": "mastercard",
        "expMonth": "12",
        "expYear": "2030",
        "last4": "4444"
      },
      "usBankAccountDetails": null,
      "linkDetails": null,
      "paymentType": "card"
    }
  ],
  "pendingPaymentMethod": null
}

POST /v1/billing/teams/{team_id}/payment-method/default

将默认支付方式设置为存档的现有支付方式。

路径参数

team_id (string, required) — 团队的团队ID。

请求体

paymentMethodId (string) — 您要设置为默认的支付方式的ID。

**请求示例：**

json

{
  "paymentMethodId": "pm_xxxxxxxxxxxxxxxxxxxxxxxx"
}

**响应示例：**

json

{}

GET /v1/billing/teams/{team_id}/postpaid/invoice/preview

预览当前计费期间的后付费使用金额。

路径参数

team_id (string, required) — 团队的团队ID。

响应体

coreInvoice (object) — 发票对象。
- lines (array<object>) — 发票上的行项目。
  - clusterName (string) — 消耗资源的集群。
  - description (string) — 行项目的描述。
  - unitType (string) — 价格测量的单位。
  - unitPrice (string) — 每单位的价格（1/1_000_000美元美分）。
  - numUnits (string) — 单位数。
  - amount (string) — 行项目的总金额（美元美分）。
- amountBeforeVatLimited (object) — 美元美分的表示。
  - val (string)
- amountBeforeVatUnlimited (object) — 美元美分的表示。
  - val (string)
- amountBeforeVatLimitedAndUnlimited (object) — 美元美分的表示。
  - val (string)
- amountBeforeVat (string)
- vatCost (string) — 增值税（美元美分）。
- amountAfterVat (string) — 增值税后的总金额（美元美分）。
- autoCreditsIssued (string) — 自动发行的信用（美元美分）。
- defaultCreditsIssued (string) — 默认发行的信用（美元美分）。
- totalWithCorr (object) — 美元美分的表示。
  - val (string)
- prepaidCredits (object) — 美元美分的表示。
  - val (string)
- prepaidCreditsUsed (object) — 美元美分的表示。
  - val (string)
effectiveSpendingLimit (string) — 当前有效的消费限额（美元美分）。
defaultCredits (string) — 当前默认信用（美元美分）。
billingCycle (object)
- year (integer)
- month (integer)

**响应示例：**

json

{
  "coreInvoice": {
    "lines": [],
    "amountBeforeVat": "0",
    "vatCost": "0",
    "amountAfterVat": "0",
    "autoCreditsIssued": "0",
    "defaultCreditsIssued": "0",
    "totalWithCorr": {
      "val": "0"
    },
    "prepaidCredits": {
      "val": "-4500"
    },
    "prepaidCreditsUsed": {
      "val": "0"
    }
  },
  "effectiveSpendingLimit": "20000",
  "defaultCredits": "0",
  "billingCycle": {
    "year": 2025,
    "month": 11
  }
}

GET /v1/billing/teams/{team_id}/postpaid/spending-limits

获取后付费月度消费限额。一旦团队用完所有预付费信用，且后付费使用金额达到用户设置的软性消费限额，API将停止工作。

路径参数

team_id (string, required) — 团队的团队ID。

响应体

spendingLimits (object) — 后付费月度消费限额。
可能不存在覆盖，因此是可选的（实际上，这来自默认的硬性消费限额覆盖或月度硬性消费限额覆盖）。
- hardSlOverride (object) — 美元美分的表示。
  - val (string)
- hardSlAuto (object) — 美元美分的表示。
  - val (string)
- effectiveHardSl (object) — 美元美分的表示。
  - val (string)
- softSl (object) — 美元美分的表示。
  - val (string)
- effectiveSl (object) — 美元美分的表示。
  - val (string)

**响应示例：**

json

{
  "spendingLimits": {
    "hardSlAuto": {
      "val": "22500"
    },
    "effectiveHardSl": {
      "val": "22500"
    },
    "softSl": {
      "val": "20000"
    },
    "effectiveSl": {
      "val": "20000"
    }
  }
}

POST /v1/billing/teams/{team_id}/postpaid/spending-limits

设置团队的后付费月度消费限额。这可用于限制后付费API使用的最大金额。请注意，这不会限制预付费信用使用量，预付费信用将始终在后付费使用累积之前被消耗。要仅使用预付费信用，您可以将此限制设置为0。

路径参数

team_id (string, required) — 团队ID。

请求体

desiredSoftSpendingLimit (object) — 美元美分的表示。
- val (string)

响应体

thisBpSoftSpendingLimit (object) — 美元美分的表示。
- val (string)

**请求示例：**

json

{
  "desiredSoftSpendingLimit": {
    "val": "20000"
  }
}

**响应示例：**

json

{
  "thisBpSoftSpendingLimit": {
    "val": "20000"
  }
}

GET /v1/billing/teams/{team_id}/prepaid/balance

列出团队的预付费信用余额和余额变更。

路径参数

team_id (string, required) — 团队的团队ID。

响应体

changes (array<object>) — 预付费信用余额的变更。
- teamId (string) — 团队ID。
- changeOrigin ("INVALID_ORIGIN" | "PURCHASE" | "SPEND" | "REFUND" | "MANUAL" | "AUTO_PURCHASE") — 变更的原因。
  - PURCHASE: 用户购买。`amount` 字段将为负数。 - SPEND: 用户消费。`amount` 字段将为正数。 - REFUND: 发放给用户的退款。`amount` 字段将为负数。 - MANUAL: 可为正或负，由xAI员工执行。 - AUTO_PURCHASE: 只能为负数。
- topupStatus ("INVALID_STATUS" | "TO_GENERATE_INVOICE" | "FAILED_TO_GEMNERATE_INVOICE" | "TO_CHARGE" | "FAILED_TO_CHARGE" | "SUCCEEDED") — 充值状态。
- amount (object) — 美元美分的表示。
  - val (string)
- invoiceId (string) — 发票ID。
- invoiceNumber (string) — 发票编号。
- createTime (string) — 发票的创建时间。
- spendBpKeyYear (integer) — 购买所在的日历年。
- spendBpKeyMonth (integer) — 购买所在的日历月。
- createTs (string) — 创建时间戳。
- paymentProcessor (object)
  - kind ("UNKNOWN" | "STRIPE" | "CHECKOUT" | "EXTERNAL" | "MANUAL")
  - externalParty (string)
  - externalInvoiceId (string)
total (object) — 美元美分的表示。
- val (string)

**响应示例：**

json

{
  "changes": [
    {
      "teamId": "65c1e471-205f-4566-9c5a-07198bcdf4ce",
      "changeOrigin": "PURCHASE",
      "topupStatus": "SUCCEEDED",
      "amount": {
        "val": "-1000"
      },
      "invoiceId": "7v7blf6c1G2g34OdI4N5tD1CKCdag4ZYLhn5vTBLIMM=",
      "invoiceNumber": "062-446-653-166",
      "createTime": "2025-02-24T15:28:02.308840Z",
      "paymentProcessor": {
        "kind": "STRIPE"
      }
    }
  ],
  "total": {
    "val": "-1000"
  }
}

POST /v1/billing/teams/{team_id}/prepaid/top-up

使用默认支付方式充值预付费信用。

路径参数

team_id (string, required) — 要充值的团队ID。

请求体

amount (object) — 美元美分的表示。
- val (string)

响应体

change (object) — 预付费信用余额的变更项。
- teamId (string) — 团队ID。
- changeOrigin ("INVALID_ORIGIN" | "PURCHASE" | "SPEND" | "REFUND" | "MANUAL" | "AUTO_PURCHASE") — 变更的原因。
  - PURCHASE: 用户购买。`amount` 字段将为负数。 - SPEND: 用户消费。`amount` 字段将为正数。 - REFUND: 发放给用户的退款。`amount` 字段将为负数。 - MANUAL: 可为正或负，由xAI员工执行。 - AUTO_PURCHASE: 只能为负数。
- topupStatus ("INVALID_STATUS" | "TO_GENERATE_INVOICE" | "FAILED_TO_GEMNERATE_INVOICE" | "TO_CHARGE" | "FAILED_TO_CHARGE" | "SUCCEEDED") — 充值状态。
- amount (object) — 美元美分的表示。
  - val (string)
- invoiceId (string) — 发票ID。

Management API ​

计费管理 ​

GET /v1/billing/teams/{team_id}/billing-info ​

路径参数 ​

响应体 ​

POST /v1/billing/teams/{team_id}/billing-info ​

路径参数 ​

请求体 ​

GET /v1/billing/teams/{team_id}/invoices ​

路径参数 ​

查询参数 ​

响应体 ​

GET /v1/billing/teams/{team_id}/payment-method ​

路径参数 ​

响应体 ​

POST /v1/billing/teams/{team_id}/payment-method/default ​

路径参数 ​

请求体 ​

GET /v1/billing/teams/{team_id}/postpaid/invoice/preview ​

路径参数 ​

响应体 ​

GET /v1/billing/teams/{team_id}/postpaid/spending-limits ​

路径参数 ​

响应体 ​

POST /v1/billing/teams/{team_id}/postpaid/spending-limits ​

路径参数 ​

请求体 ​

响应体 ​

GET /v1/billing/teams/{team_id}/prepaid/balance ​

路径参数 ​

响应体 ​

POST /v1/billing/teams/{team_id}/prepaid/top-up ​

路径参数 ​

请求体 ​

响应体 ​

Management API

计费管理

GET /v1/billing/teams/{team_id}/billing-info

路径参数

响应体

POST /v1/billing/teams/{team_id}/billing-info

路径参数

请求体

GET /v1/billing/teams/{team_id}/invoices

路径参数

查询参数

响应体

GET /v1/billing/teams/{team_id}/payment-method

路径参数

响应体

POST /v1/billing/teams/{team_id}/payment-method/default

路径参数

请求体

GET /v1/billing/teams/{team_id}/postpaid/invoice/preview

路径参数

响应体

GET /v1/billing/teams/{team_id}/postpaid/spending-limits

路径参数

响应体

POST /v1/billing/teams/{team_id}/postpaid/spending-limits

路径参数

请求体

响应体

GET /v1/billing/teams/{team_id}/prepaid/balance

路径参数

响应体

POST /v1/billing/teams/{team_id}/prepaid/top-up

路径参数

请求体

响应体