账单和用量
接口概述
账单和用量接口用于查询和管理账单信息、使用量统计、计费规则等。
基本信息
- 接口路径：
/v1/organizations/{organization_id}/billing - 需要认证：是
- 请求方式：GET
- 数据格式：JSON
API 接口
获取账单概览
请求
GET /v1/organizations/{organization_id}/billing/summary
Authorization: Bearer your-api-key响应
{
"status_code": 200,
"status_message": "SUCCESS",
"data": {
"current_period": {
"start_date": "2024-02-01T00:00:00Z",
"end_date": "2024-02-29T23:59:59Z",
"total_amount": 1234.56,
"currency": "CNY",
"status": "active"
},
"balance": {
"available": 5000.00,
"reserved": 100.00,
"currency": "CNY"
},
"payment_method": {
"type": "credit_card",
"last4": "4242",
"expiry": "12/25"
},
"subscription": {
"plan": "enterprise",
"status": "active",
"next_billing_date": "2024-03-01T00:00:00Z"
}
}
}获取账单详情
请求
GET /v1/organizations/{organization_id}/billing/invoices
Authorization: Bearer your-api-key响应
{
"status_code": 200,
"status_message": "SUCCESS",
"data": {
"invoices": [
{
"id": "inv_123456",
"period_start": "2024-01-01T00:00:00Z",
"period_end": "2024-01-31T23:59:59Z",
"amount": 1234.56,
"currency": "CNY",
"status": "paid",
"payment_date": "2024-02-01T10:00:00Z",
"items": [
{
"description": "对话接口调用",
"quantity": 100000,
"unit_price": 0.01,
"amount": 1000.00
},
{
"description": "向量接口调用",
"quantity": 50000,
"unit_price": 0.005,
"amount": 250.00
}
]
}
],
"total": 1,
"page": 1,
"page_size": 10
}
}获取使用量统计
请求
GET /v1/organizations/{organization_id}/billing/usage
Authorization: Bearer your-api-key
Content-Type: application/json
{
"start_date": "2024-02-01T00:00:00Z",
"end_date": "2024-02-29T23:59:59Z",
"group_by": "day"
}响应
{
"status_code": 200,
"status_message": "SUCCESS",
"data": {
"usage": [
{
"date": "2024-02-01",
"chat": {
"requests": 1000,
"tokens": {
"prompt": 50000,
"completion": 30000
},
"amount": 100.00
},
"embeddings": {
"requests": 500,
"tokens": 25000,
"amount": 50.00
}
}
],
"total": {
"chat": {
"requests": 1000,
"tokens": {
"prompt": 50000,
"completion": 30000
},
"amount": 100.00
},
"embeddings": {
"requests": 500,
"tokens": 25000,
"amount": 50.00
}
}
}
}获取项目使用量
请求
GET /v1/organizations/{organization_id}/projects/{project_id}/usage
Authorization: Bearer your-api-key
Content-Type: application/json
{
"start_date": "2024-02-01T00:00:00Z",
"end_date": "2024-02-29T23:59:59Z",
"group_by": "day"
}响应
{
"status_code": 200,
"status_message": "SUCCESS",
"data": {
"project_id": "proj_def456",
"project_name": "我的项目",
"usage": [
{
"date": "2024-02-01",
"api_key_id": "key_ghi789",
"api_key_name": "开发环境密钥",
"chat": {
"requests": 500,
"tokens": {
"prompt": 25000,
"completion": 15000
},
"amount": 50.00
},
"embeddings": {
"requests": 250,
"tokens": 12500,
"amount": 25.00
}
}
],
"total": {
"chat": {
"requests": 500,
"tokens": {
"prompt": 25000,
"completion": 15000
},
"amount": 50.00
},
"embeddings": {
"requests": 250,
"tokens": 12500,
"amount": 25.00
}
}
}
}获取计费规则
请求
GET /v1/billing/pricing
Authorization: Bearer your-api-key响应
{
"status_code": 200,
"status_message": "SUCCESS",
"data": {
"models": {
"zgi-1": {
"chat": {
"prompt_tokens": 0.002,
"completion_tokens": 0.002,
"currency": "CNY"
}
},
"zgi-1-pro": {
"chat": {
"prompt_tokens": 0.004,
"completion_tokens": 0.004,
"currency": "CNY"
}
},
"zgi-embedding-1": {
"embeddings": {
"tokens": 0.001,
"currency": "CNY"
}
}
},
"volume_discounts": [
{
"threshold": 1000000,
"discount": 0.1
},
{
"threshold": 5000000,
"discount": 0.2
}
]
}
}错误码
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| 400 | 请求参数错误 | 检查请求参数是否符合要求 |
| 401 | 未授权 | 检查 API 密钥是否有效 |
| 403 | 权限不足 | 检查用户是否有相应的操作权限 |
| 404 | 资源不存在 | 检查请求的资源是否存在 |
| 429 | 请求过于频繁 | 遵循 API 调用限制 |
计费说明
1. 计费项目
- 对话接口：按 prompt 和 completion tokens 分别计费
- 向量接口：按输入 tokens 计费
- 存储费用：按存储容量和时长计费
- 带宽费用：按流量计费
2. 计费规则
- 预付费：预充值后使用
- 后付费：月度结算
- 阶梯定价：用量越大单价越低
- 保底费用：基础服务费
3. 优惠政策
- 新用户优惠
- 批量采购折扣
- 长期合作优惠
- 特殊项目折扣
使用建议
1. 成本优化
- 合理选择模型
- 优化输入长度
- 使用缓存机制
- 批量处理请求
2. 用量监控
- 设置用量预警
- 定期审查使用情况
- 分析使用趋势
- 优化资源配置
3. 最佳实践
- 制定预算计划
- 监控异常消费
- 定期对账核算
- 优化计费模式