پرش به محتوا

موجودی و گزارش مصرف

با GET /me موجودی و محدودیت‌های کلید را بخوانید، با GET /usage گزارش مصرف روزانه یا به تفکیک مدل بگیرید و با GET /requests/{id} وضعیت یک درخواست را ببینید.

بازبینی: ۸ مهر ۱۴۰۵ ۵ دقیقه مطالعه

سه endpoint برای این‌که بدانید چقدر اعتبار دارید و کجا خرج شده است. هر سه با همان کلید کار می‌کنند و هزینه‌ای ندارند. همین اطلاعات را با نمودار در اپ گیسو، بخش API هم می‌بینید.

موجودی و محدودیت‌های کلید: GET /me#

GEThttps://gisoo.pro/api/v1/me
cURL GET /me
curl https://gisoo.pro/api/v1/me -H "Authorization: Bearer $GISOO_API_KEY"
JSON پاسخ
{
  "object": "account",
  "balance": { "usd": "12.408114", "usd_display": "$12.4081" },
  "status": "active",
  "project": { "id": 42, "name": "support-bot" },
  "key": {
    "name": "production",
    "prefix": "sk-gisoo-v1-Xy7Q",
    "rpm_limit": 60,
    "spend_limit_usd": "20.00",
    "spent_usd": "3.591886",
    "expires_at": null
  },
  "limits": { "concurrency": 8, "max_request_kb": 20480 }
}
  • balance.usd موجودی حساب به دلار، با شش رقم اعشار؛ usd_display همان برای نمایش.
  • status حساب: active یا suspended.
  • key.spend_limit_usd سقف هزینهٔ همین کلید (null یعنی بدون سقف) و key.spent_usd مقداری که تا حالا خرج کرده است.
  • key.rpm_limit و limits.concurrency سقف‌هایی است که در این لحظه روی کلید و حساب اعمال می‌شود؛ limits.max_request_kb بیشترین حجم بدنه.
Python بررسی موجودی پیش از کار دسته‌ای
# A small guard: stop the batch job before the balance runs out.
import requests, os

HEADERS = {"Authorization": "Bearer " + os.environ["GISOO_API_KEY"]}

def balance_usd() -> float:
    me = requests.get("https://gisoo.pro/api/v1/me", headers=HEADERS, timeout=15).json()
    return float(me["balance"]["usd"])

if balance_usd() < 1.0:
    raise SystemExit("Balance under $1 — top up before running the batch.")

گزارش مصرف: GET /usage#

GEThttps://gisoo.pro/api/v1/usage

مصرف پروژه‌ای که کلید به آن تعلق دارد، روزبه‌روز یا به تفکیک مدل:

from date
آغاز بازه، مثل 2026-09-01. پیش‌فرض ۲۹ روز پیش.
to date
پایان بازه. پیش‌فرض امروز.
group string
day (پیش‌فرض) یا model.
scope string
پیش‌فرض همهٔ کلیدهای پروژه؛ key فقط همین کلید.
cURL GET /usage
# Last 30 days, day by day (default)
curl "https://gisoo.pro/api/v1/usage" -H "Authorization: Bearer $GISOO_API_KEY"

# September, per model, only this key
curl "https://gisoo.pro/api/v1/usage?from=2026-09-01&to=2026-09-30&group=model&scope=key" \
  -H "Authorization: Bearer $GISOO_API_KEY"
JSON پاسخ
{
  "object": "usage",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "group": "model",
  "total_usd": "1.284000",
  "data": [
    { "key": "gpt-4o-mini", "requests": 812, "errors": 3, "input_tokens": 1204511, "output_tokens": 301877, "usd": "0.506100" },
    { "key": "text-embedding-3-small", "requests": 40, "errors": 0, "input_tokens": 902114, "output_tokens": 0, "usd": "0.025300" }
  ]
}

تاریخ‌ها روز تقویم میلادی‌اند. مبلغ‌ها به دلار و شامل همهٔ درخواست‌های موفق بازه‌اند؛ درخواست ناموفق در errors شمرده می‌شود و هزینه ندارد.

هزینهٔ یک درخواست: GET /requests/{id}#

GEThttps://gisoo.pro/api/v1/requests/{id}

شناسه همان id پاسخ (برای Chat Completions) یا هدر X-Request-Id هر پاسخ است و با req_ شروع می‌شود. فقط درخواست‌های همان پروژه دیده می‌شوند.

cURL GET /requests/{id}
curl https://gisoo.pro/api/v1/requests/req_4b1f0c9a7e2d8f3a6c5b0e1d -H "Authorization: Bearer $GISOO_API_KEY"
JSON پاسخ
{
  "id": "req_4b1f0c9a7e2d8f3a6c5b0e1d",
  "object": "request",
  "created": 1790000000,
  "model": "gpt-4o-mini",
  "endpoint": "chat",
  "status": "success",
  "streamed": true,
  "usage": { "input_tokens": 1500, "output_tokens": 500, "cached_tokens": 1024, "total_tokens": 2000 },
  "usd": "0.000628",
  "latency_ms": 1840,
  "error": null
}
  • status: success، error، pending (پاسخ جریانی هنوز باز است) یا cancelled.
  • usd هزینهٔ نهایی همین درخواست.
  • برای درخواست ناموفق، error کد و پیام خطا را دارد.
Python ثبت هزینهٔ هر درخواست در لاگ خودتان
# Log what each request cost, from the id the response already gave you.
reply = client.chat.completions.with_raw_response.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hi"}],
)
request_id = reply.headers.get("x-request-id")    # also completion.id for chat completions
completion = reply.parse()

info = requests.get("https://gisoo.pro/api/v1/requests/" + request_id, headers=HEADERS, timeout=15).json()
print(request_id, info["usd"], info["usage"])
متن درخواست‌ها نگه داشته نمی‌شود

این گزارش‌ها از فرادادهٔ درخواست‌ها ساخته می‌شوند: مدل، تعداد توکن، هزینه، زمان و IP. متن پرامپت و پاسخ مدل در گیسو ذخیره نمی‌شود؛ اگر برای بررسی بعدی لازمشان دارید، در سیستم خودتان نگه دارید.

پاسخ پرسشتان را پیدا نکردید؟

شناسهٔ درخواست (هدر X-Request-Id) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.

تیکت پشتیبانی