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

获取指定团队 ID 的账单信息。

路径参数

team_idstring

（字符串，必需）— 团队 ID。

响应体

billingInfoobject

（对象）——账单信息。

No parameters.

{
  "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"
  }
}

设置账单信息

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

设置团队的计费信息。

路径参数

team_idstring

（字符串，必需）— 团队 ID。

请求体

{
  "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"
  }
}

{}

列出发票

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

列出属于团队的发票。

路径参数

team_idstring

（字符串，必需）— 团队 ID。

查询参数

billingCycle.yearinteger

billingCycle.monthinteger

since.yearinteger

since.monthinteger

invoiceIds.invoiceIdsarray<string>

（数组<字符串>）

响应体

invoicesarray<object>

发票。

No parameters.

{
  "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"
      }
    }
  ]
}

列出付款方式

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

列出团队已保存的付款方式。你可以添加或删除付款方式https://console.x.ai.

路径参数

team_idstring

（字符串，必需）— 团队 ID。

响应体

paymentMethodsarray<object>

已保存的付款方式。

pendingPaymentMethodobject

表示添加付款方式的不完整尝试。可能会转化为付款方式。

No parameters.

{
  "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
}

设置默认付款方式

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

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

路径参数

team_idstring

（字符串，必需）— 团队 ID。

请求体

{
  "paymentMethodId": "pm_xxxxxxxxxxxxxxxxxxxxxxxx"
}

{}

预览本月 postpaid 发票

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

预览当前计费周期后付费用量的应付金额。

路径参数

team_idstring

（字符串，必需）— 团队 ID。

响应体

coreInvoiceobject

发票对象。

effectiveSpendingLimitstring

当前有效支出限额，以 USD 美分为单位。

defaultCreditsstring

（字符串）— 当前默认额度（单位：USD 美分）。

billingCycleobject

No parameters.

{
  "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
  }
}

获取每月 postpaid 消费限额

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

获取后付费每月支出限额。团队耗尽全部预付费额度且后付费用量达到用户设置的软支出限额后，API 将停止工作。

路径参数

team_idstring

（字符串，必需）— 团队 ID。

响应体

spendingLimitsobject

（对象）— 后付费每月支出限额。

No parameters.

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

设置每月 postpaid 消费限额

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

设置团队的后付费每月支出限额，可用于限制后付费 API 用量的最高金额。请注意，这不会限制预付费额度的使用；预付费额度总会先于后付费用量被消耗。若只想使用预付费额度，可将此限额设为 0。

路径参数

team_idstring

（字符串，必需）— 团队 ID。

请求体

响应体

thisBpSoftSpendingLimitobject

USD 美分的表示。

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

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

列出 prepaid credit 余额和余额变更

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

列出团队的预付费额度余额及其变化。

路径参数

team_idstring

（字符串，必需）— 团队 ID。

响应体

changesarray<object>

预付费额度余额的变化。

totalobject

USD 美分的表示。

No parameters.

{
  "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"
  }
}

充值 prepaid credit

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

使用默认付款方式为预付费额度充值。

路径参数

team_idstring

（字符串，必填）— 要充值的团队的团队 ID。

请求体

响应体

changeobject

（对象）— 预付费额度余额的变动项。

{
  "amount": {
    "val": "500"
  }
}

{
  "change": {
    "teamId": "65c1e471-205f-4566-9c5a-07198bcdf4ce",
    "changeOrigin": "PURCHASE",
    "topupStatus": "TO_CHARGE",
    "amount": {
      "val": "-500"
    },
    "createTime": "2025-11-13T14:02:21.309537Z",
    "createTs": "2025-11-13T14:02:21.309537Z",
    "paymentProcessor": {
      "kind": "STRIPE"
    }
  }
}

每日 token 用量

POST /v1/billing/teams/{team_id}/usage 以时间序列返回团队用量，按时间分桶，也可按 token 类型、模型等字段分组。它与 Usage Explorer 使用相同的数据。请使用管理密钥进行身份验证。

通过以下字段选择统计指标：values[].name。各指标均只支持 AGGREGATION_SUM.

值	统计内容
`usd`	以美元计的费用
`units`	对 token 类用量统计 token 数，其他类型则统计各自的单位，例如图像张数或音频秒数
`items`	计费项数；一个请求的每个计价维度各产生一项
`transactions`	请求数

可用于分组和筛选的字段包括 unit_type、description、api_key_id、product、request_ip、user_id 和 unit_price。unit_type 表示 token 类型，例如 Prompt text tokens、Cached prompt text tokens、Completion text tokens 或 Reasoning text tokens。Prompt text tokens 仅统计未缓存的输入，缓存输入计入 Cached prompt text tokens。description 是产品名称，后接计费资源（通常为模型）。

以下请求按 token 类型和模型返回每日 token 数：

curl https://management-api.x.ai/v1/billing/teams/{team_id}/usage \
  -X POST \
  -H "Authorization: Bearer $XAI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "analyticsRequest": {
          "timeRange": {
            "startTime": "2026-10-26 00:00:00",
            "endTime": "2026-11-03 00:00:00",
            "timezone": "Etc/GMT"
          },
          "timeUnit": "TIME_UNIT_DAY",
          "values": [{ "name": "units", "aggregation": "AGGREGATION_SUM" }],
          "groupBy": ["unit_type", "description"],
          "filters": []
        }
      }'

响应中的 timeSeries 为每种分组值组合提供一个条目。其中的 group 数组按 groupBy 的顺序列出各值，在本例中先列 token 类型，再列描述。dataPoints 对范围内的每一天各有一个条目，values[0] 保存当天的 token 数量。

startTime 和 endTime 的格式为 YYYY-MM-DD HH:MM:SS，采用的 IANA 时区由 timezone 指定，该时区也决定每天的起止时间。endTime 不包含在查询范围内。
请将 unit_type 保留在 groupBy 中，以便正确统计 units。如果仅按 description 分组，就会把同一模型的所有单位类型相加为一个数值。
如果 limitReached 为 true，说明响应已达到行数上限，数据可能不完整。请缩短时间范围或减少分组字段。
未知的指标或字段名会返回 HTTP 400。

区分长上下文和短上下文的 token

长上下文请求的费率更高（见价格），但其 token 使用与其他 token 相同的 unit_type 和 description。要区分它们，请添加 unit_price 到 groupBy 中，使上述请求为每种价格返回独立的时间序列：

"groupBy": ["unit_type", "description", "unit_price"]

unit_price 的单位是每单位 1e-10 美元，因此将其除以 10,000 即可得到每百万 token 的美元价格。例如，"25000" 表示每百万 token 为 2.50 美元。将各序列与模型的标准和长上下文费率对照，即可区分。相同 token 类型和模型也可能因美国区域端点费率、自定义定价或时间范围内的价格变动产生其他序列。若只需部分价格，可筛选 unit_price，例如 "filters": ["unit_price:>12500"].

获取 API 历史用量

/v1/billing/teams/{team_id}/usage

获取指定时段内 API 的历史用量（支出、token 数和其他计费单位数），按时间分桶并按字段分组。若需获取每日 token 数，请按天对 `units` 求和，并按 `unit_type` 分组。

路径参数

team_idstring

（字符串，必需）— 要分析其计费记录的团队。

请求体

响应体

timeSeriesarray<object>

对于 group-by 子句的每个值，我们返回一个时间序列。

limitReachedboolean

（布尔值）— 如果为 true，说明查询已达到最大基数，返回的仅是结果子集。

{
  "analyticsRequest": {
    "timeRange": {
      "startTime": "2025-10-01 00:00:00",
      "endTime": "2025-10-08 00:00:00",
      "timezone": "Etc/GMT"
    },
    "timeUnit": "TIME_UNIT_DAY",
    "values": [
      {
        "name": "units",
        "aggregation": "AGGREGATION_SUM"
      }
    ],
    "groupBy": [
      "unit_type",
      "description"
    ],
    "filters": []
  }
}

{
  "timeSeries": [
    {
      "group": [
        "Chat grok-4-0709"
      ],
      "groupLabels": [
        "Chat grok-4-0709"
      ],
      "dataPoints": [
        {
          "timestamp": "2025-10-01T00:00:00Z",
          "values": [
            0.75973725
          ]
        },
        {
          "timestamp": "2025-10-02T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-03T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-04T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-05T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-06T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-07T00:00:00Z",
          "values": [
            0
          ]
        }
      ]
    },
    {
      "group": [
        "Chat grok-4-fast-non-reasoning"
      ],
      "groupLabels": [
        "Chat grok-4-fast-non-reasoning"
      ],
      "dataPoints": [
        {
          "timestamp": "2025-10-01T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-02T00:00:00Z",
          "values": [
            0.0001037
          ]
        },
        {
          "timestamp": "2025-10-03T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-04T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-05T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-06T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-07T00:00:00Z",
          "values": [
            0
          ]
        }
      ]
    },
    {
      "group": [
        "grok-2-image-1212"
      ],
      "groupLabels": [
        "grok-2-image-1212"
      ],
      "dataPoints": [
        {
          "timestamp": "2025-10-01T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-02T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-03T00:00:00Z",
          "values": [
            0.14
          ]
        },
        {
          "timestamp": "2025-10-04T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-05T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-06T00:00:00Z",
          "values": [
            0
          ]
        },
        {
          "timestamp": "2025-10-07T00:00:00Z",
          "values": [
            0
          ]
        }
      ]
    }
  ],
  "limitReached": false
}

最后更新：2026 年 11 月 3 日