الانتقال إلى المحتوى الرئيسي
GET
/
billing
/
usage-analytics
/api/v1/billing/usage-analytics
curl --request GET \
  --url https://api.venice.ai/api/v1/billing/usage-analytics \
  --header 'Authorization: Bearer <token>'
{
  "lookback": "7d",
  "byDate": [
    {
      "date": "2024-01-15T00:00:00.000Z",
      "USD": 0.5,
      "DIEM": 10.25
    },
    {
      "date": "2024-01-14T00:00:00.000Z",
      "USD": 0.3,
      "DIEM": 8.75
    }
  ],
  "byModel": [
    {
      "modelName": "GLM 5.1",
      "unitType": "tokens",
      "modelType": "LLM",
      "totalUsd": 0.4,
      "totalDiem": 12.5,
      "totalUnits": 50000,
      "breakdown": [
        {
          "type": "Output",
          "usd": 0.3,
          "diem": 10,
          "units": 35000
        },
        {
          "type": "Input",
          "usd": 0.1,
          "diem": 2.5,
          "units": 15000
        }
      ]
    }
  ],
  "byModelDaily": [
    {
      "date": 1705276800000,
      "GLM 5.1": 5.5,
      "Kimi K2.6": 3.2
    }
  ],
  "topModels": [
    "GLM 5.1",
    "Kimi K2.6"
  ],
  "byKey": [
    {
      "apiKeyId": "key_abc123",
      "description": "Production Key",
      "totalUsd": 0.8,
      "totalDiem": 15,
      "totalUnits": 75000
    },
    {
      "apiKeyId": null,
      "description": "Web App",
      "totalUsd": 0,
      "totalDiem": 4,
      "totalUnits": 25000
    }
  ],
  "byKeyDaily": [
    {
      "date": 1705276800000,
      "Production Key": 8.5,
      "Web App": 2
    }
  ],
  "topKeyNames": [
    "Production Key",
    "Web App"
  ]
}
هذه endpoint بيتا وقد تكون غير مستقرة أو تتغير دون إشعار.
احصل على تحليلات استخدام مُجمَّعة للمستخدم المُصادَق عليه، مع تفصيل حسب التاريخ والنموذج ومفتاح API. توفّر هذه الـ endpoint عروض ملخّصة لبيانات استخدام API لبناء لوحات المعلومات ومراقبة الاستهلاك. يتم تخزين البيانات مؤقتًا لمدة 10 دقائق.

​
معاملات الاستعلام

يمكنك تحديد الفترة الزمنية للتحليلات باستخدام إما:
  • lookback: فترة نسبية مثل “7d” (7 أيام)، “30d” (30 يومًا)، حتى “90d” (90 يومًا)
  • startDate و endDate: نطاق تاريخ مخصص بصيغة YYYY-MM-DD. كلاهما مطلوب إذا تم توفير أي منهما.
إذا لم يتم تحديد أي معاملات، فإن فترة lookback الافتراضية هي 7 أيام.

​
حقول الاستجابة

​
lookback

فترة lookback المستخدمة في الاستعلام. إما بصيغة “Nd” (مثل “7d”) أو بصيغة “startDate:endDate”.

​
byDate

إجماليات الاستخدام اليومية للفترة المطلوبة.
  • date: التاريخ بصيغة YYYY-MM-DD
  • USD: إجمالي الاستخدام بالدولار الأمريكي لذلك اليوم
  • DIEM: إجمالي الاستخدام بـ DIEM لذلك اليوم

​
byModel

تفصيل الاستخدام حسب النموذج، مُرتَّب حسب إجمالي الإنفاق (الأعلى أولًا).
  • modelName: الاسم المعروض للنموذج (مثل “GLM 5”)
  • unitType: نوع الوحدات المستهلكة (tokens، images، chars، minutes، seconds)
  • modelType: نوع النموذج (LLM، IMAGE، TTS، ASR، VIDEO)، أو null
  • totalUsd: إجمالي الدولارات المُنفَقة على هذا النموذج
  • totalDiem: إجمالي DIEM المُنفَقة على هذا النموذج
  • totalUnits: إجمالي الوحدات المستهلكة لهذا النموذج
  • breakdown: مصفوفة من تفصيلات الاستخدام حسب النوع (متوفر فقط إذا كانت هناك أنواع متعددة). كل إدخال يحتوي على:
    • type: نوع الـ token (مثل “Input”، “Output”، “Cache Read”، “Cache Write”)
    • usd: المبلغ بالدولار لهذا التفصيل
    • diem: المبلغ بـ DIEM لهذا التفصيل
    • units: عدد الوحدات لهذا التفصيل

​
byModelDaily

بيانات الرسم البياني اليومية لأفضل 8 نماذج. يحتوي كل إدخال على “date” (طابع زمني) بالإضافة إلى أسماء النماذج كمفاتيح مع قيم استخدام DIEM.

​
topModels

مصفوفة من أسماء أفضل 8 نماذج حسب الاستخدام، لوسائل إيضاح الرسوم البيانية.

​
byKey

تفصيل الاستخدام حسب مفتاح API، مُرتَّب حسب إجمالي الإنفاق (الأعلى أولًا).
  • apiKeyId: معرّف مفتاح API، أو null إذا كان الاستخدام من تطبيق الويب
  • description: وصف مفتاح API أو “Web App”
  • totalUsd: إجمالي الدولارات المُنفَقة عبر هذا المفتاح
  • totalDiem: إجمالي DIEM المُنفَقة عبر هذا المفتاح
  • totalUnits: إجمالي الوحدات المستهلكة عبر هذا المفتاح

​
byKeyDaily

بيانات الرسم البياني اليومية لأفضل 8 مفاتيح API. يحتوي كل إدخال على “date” (طابع زمني) بالإضافة إلى أوصاف المفاتيح كمفاتيح مع قيم استخدام DIEM.

​
topKeyNames

مصفوفة من أوصاف أفضل 8 مفاتيح API حسب الاستخدام، لوسائل إيضاح الرسوم البيانية.

​
أمثلة الاستخدام

# الحصول على تحليلات الاستخدام لآخر 7 أيام (الافتراضي)
curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics" \
  -H "Authorization: Bearer YOUR_API_KEY"

# الحصول على تحليلات الاستخدام لآخر 30 يومًا
curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

# الحصول على تحليلات الاستخدام لنطاق تاريخ محدد
curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

التفويضات

​
Authorization
string
header
مطلوب

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

معلمات الاستعلام

​
lookback
string
افتراضي:7d

Lookback period for usage data. Format: number followed by "d" (e.g., "7d", "30d"). Maximum: 90d

Pattern: ^[1-9]\d*d$
مثال:

"7d"

​
startDate
string

Start date for filtering records (YYYY-MM-DD). If provided, endDate is also required.

Pattern: ^\d{4}-\d{2}-\d{2}$
مثال:

"2024-01-01T00:00:00.000Z"

​
endDate
string

End date for filtering records (YYYY-MM-DD). If provided, startDate is also required.

Pattern: ^\d{4}-\d{2}-\d{2}$
مثال:

"2024-01-31T00:00:00.000Z"

الاستجابة

Successful response with aggregated usage analytics

Aggregated usage analytics response with breakdowns by date, model, and API key

​
lookback
string
مطلوب

The lookback period used for the query. Either "Nd" format or "startDate:endDate" format.

مثال:

"7d"

​
byDate
object[]
مطلوب

Daily usage totals for the requested period

​
byModel
object[]
مطلوب

Usage breakdown by model, sorted by total spend (highest first)

​
byModelDaily
object[]
مطلوب

Daily chart data for top 8 models. Each entry has "date" (timestamp) plus model names as keys.

​
topModels
string[]
مطلوب

Names of the top 8 models by usage (for chart legends)

​
byKey
object[]
مطلوب

Usage breakdown by API key, sorted by total spend (highest first)

​
byKeyDaily
object[]
مطلوب

Daily chart data for top 8 API keys. Each entry has "date" (timestamp) plus key descriptions as keys.

​
topKeyNames
string[]
مطلوب

Descriptions of the top 8 API keys by usage (for chart legends)