用量明细查询

# 用量明细查询 **Base URL:** `https://openapi.tripo3d.com/v3` **Endpoint:** `GET /account/usage/history` 按 API Key 查询某个时间窗内创建、且**已成功**的任务及每个任务消耗的积分，按创建时间倒序返回。 面向自动化对账：不返回提示词、输入、产物或任何下载链接。 - 查询范围是发起请求的 API Key；需要汇总多个 Key 时请分别查询。 - 只返回成功任务；失败、过期或审核未通过的任务（通常已退回积分）不在结果中，因此不能直接与账单流水逐条对账。 - 按任务创建时间筛选。查询时仍在运行的任务尚未成功，建议只查询结束时间早于当前 30 分钟以上的时间窗。 - 限流：每个 API Key 每分钟 60 次，超出返回 `429` 并带 `Retry-After` 响应头。 - 错误：参数不合法返回 `400`（`code=1004`）；服务端临时异常返回 `503`（`code=1008`）并带 `Retry-After`，原样重试即可。 ## Request Parameters ### start_time - **Type:** string - **Required:** 必选 时间窗起点（包含）。RFC 3339 格式且必须带时区偏移，例如 `2026-10-01T00:00:00Z` 或 `2026-10-01T00:00:00+08:00`。 ### end_time - **Type:** string - **Required:** 必选 时间窗终点（不包含）。格式同 start_time；必须晚于 start_time，且与其相差不超过 31 天。 ### page_size - **Type:** integer - **Required:** 可选 - **Default:** `100` 每页条数，1–100。 ### cursor - **Type:** string - **Required:** 可选 上一页返回的 next_cursor。翻页期间 start_time 与 end_time 保持不变；首页不传。 ## Response Fields ### items - **Type:** array - **Required:** 必选 本页任务，按创建时间倒序。 ### items[].task_id - **Type:** string - **Required:** 必选 任务 ID。 ### items[].type - **Type:** string - **Required:** 必选 任务类型，与任务查询返回值一致。 ### items[].model_version - **Type:** string - **Required:** 可选 创建时记录的模型版本；该任务类型没有版本时不返回。 ### items[].status - **Type:** string - **Required:** 必选 固定为 success。 ### items[].created_at - **Type:** string - **Required:** 必选 创建时间，UTC 的 ISO 8601 格式。 ### items[].completed_at - **Type:** string - **Required:** 可选 完成时间，UTC 的 ISO 8601 格式；未记录时不返回。 ### items[].credits_consumed - **Type:** number - **Required:** 必选 该任务扣除的积分，与任务查询中的 credits_consumed 一致；未扣费为 0。 ### has_more - **Type:** boolean - **Required:** 必选 是否还有下一页。 ### next_cursor - **Type:** string - **Required:** 必选 作为 cursor 传入以获取下一页；最后一页为 null。 ## Request Example ### 首页 ``` curl -s -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "start_time=2026-10-01T00:00:00+08:00" \ --data-urlencode "end_time=2026-11-01T00:00:00+08:00" \ https://openapi.tripo3d.com/v3/account/usage/history ``` ### Python（翻完所有页） ``` import time import requests API_KEY = "YOUR_API_KEY" url = "https://openapi.tripo3d.com/v3/account/usage/history" params = { "start_time": "2026-10-01T00:00:00+08:00", "end_time": "2026-11-01T00:00:00+08:00", "page_size": 100, } total = 0.0 while True: r = requests.get(url, params=params, headers={"Authorization": f"Bearer {API_KEY}"}) if r.status_code in (429, 503): time.sleep(int(r.headers.get("Retry-After", "5"))) continue r.raise_for_status() data = r.json()["data"] for item in data["items"]: total += item["credits_consumed"] if not data["has_more"]: break params["cursor"] = data["next_cursor"] print(f"credits consumed: {total:.2f}") ``` ## Response Example ### 分页结果 ```json { "code": 0, "status": "success", "data": { "items": [ { "task_id": "123e4567-e89b-42d3-a456-426614174000", "type": "text_to_model", "model_version": "v3.0-20250812", "status": "success", "created_at": "2026-10-31T15:59:58.123456Z", "completed_at": "2026-10-31T16:01:12.654321Z", "credits_consumed": 30.00 } ], "has_more": true, "next_cursor": "djE6MTc2MTkyNjM5ODEyMzQ1NjoxMjNlNDU2Ny1lODliLTQyZDMtYTQ1Ni00MjY2MTQxNzQwMDA" } } ```

curl -s -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "start_time=2026-10-01T00:00:00+08:00" \
  --data-urlencode "end_time=2026-11-01T00:00:00+08:00" \
  https://openapi.tripo3d.com/v3/account/usage/history

import time
import requests

API_KEY = "YOUR_API_KEY"
url = "https://openapi.tripo3d.com/v3/account/usage/history"
params = {
    "start_time": "2026-10-01T00:00:00+08:00",
    "end_time": "2026-11-01T00:00:00+08:00",
    "page_size": 100,
}
total = 0.0
while True:
    r = requests.get(url, params=params, headers={"Authorization": f"Bearer {API_KEY}"})
    if r.status_code in (429, 503):
        time.sleep(int(r.headers.get("Retry-After", "5")))
        continue
    r.raise_for_status()
    data = r.json()["data"]
    for item in data["items"]:
        total += item["credits_consumed"]
    if not data["has_more"]:
        break
    params["cursor"] = data["next_cursor"]
print(f"credits consumed: {total:.2f}")

{
  "code": 0,
  "status": "success",
  "data": {
    "items": [
      {
        "task_id": "123e4567-e89b-42d3-a456-426614174000",
        "type": "text_to_model",
        "model_version": "v3.0-20250812",
        "status": "success",
        "created_at": "2026-10-31T15:59:58.123456Z",
        "completed_at": "2026-10-31T16:01:12.654321Z",
        "credits_consumed": 30.00
      }
    ],
    "has_more": true,
    "next_cursor": "djE6MTc2MTkyNjM5ODEyMzQ1NjoxMjNlNDU2Ny1lODliLTQyZDMtYTQ1Ni00MjY2MTQxNzQwMDA"}
}