Análise de uso de cobrança | Documentação da API Venice

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>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.venice.ai/api/v1/billing/usage-analytics', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.venice.ai/api/v1/billing/usage-analytics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.venice.ai/api/v1/billing/usage-analytics"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.venice.ai/api/v1/billing/usage-analytics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

{
  "error": "<string>",
  "details": {
    "_errors": [],
    "field": {
      "_errors": [
        "Field is required"
      ]
    }
  }
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Este é um endpoint beta e pode estar instável ou mudar sem aviso prévio.

Obtenha análises agregadas de uso para o usuário autenticado, com divisões por data, modelo e chave de API. Este endpoint fornece visualizações resumidas dos seus dados de uso da API para construir dashboards e monitorar o consumo. Os dados são armazenados em cache por 10 minutos.

Parâmetros de consulta

Você pode especificar o período para as análises usando:

lookback: Um período relativo como “7d” (7 dias), “30d” (30 dias), até “90d” (90 dias)
startDate e endDate: Um intervalo de datas personalizado no formato YYYY-MM-DD. Ambos são obrigatórios se um deles for fornecido.

Se nenhum parâmetro for especificado, o período padrão de lookback é de 7 dias.

Campos de resposta

lookback

O período de lookback usado na consulta. No formato “Nd” (por exemplo, “7d”) ou no formato “startDate:endDate”.

byDate

Totais diários de uso para o período solicitado.

date: A data no formato YYYY-MM-DD
USD: Uso total em USD para aquele dia
DIEM: Uso total em DIEM para aquele dia

byModel

Detalhamento de uso por modelo, ordenado por gasto total (do maior para o menor).

modelName: Nome de exibição do modelo (por exemplo, “GLM 5”)
unitType: Tipo de unidades consumidas (tokens, imagens, caracteres, minutos, segundos)
modelType: Tipo de modelo (LLM, IMAGE, TTS, ASR, VIDEO) ou nulo
totalUsd: Total em USD gasto neste modelo
totalDiem: Total em DIEM gasto neste modelo
totalUnits: Total de unidades consumidas para este modelo
breakdown: Array de detalhamentos de uso por tipo (presente apenas se houver múltiplos tipos). Cada entrada contém:
- type: Tipo de token (por exemplo, “Input”, “Output”, “Cache Read”, “Cache Write”)
- usd: Valor em USD para este detalhamento
- diem: Valor em DIEM para este detalhamento
- units: Número de unidades para este detalhamento

byModelDaily

Dados diários de gráfico para os 8 principais modelos. Cada entrada contém uma “date” (timestamp) mais nomes de modelos como chaves com valores de uso em DIEM.

topModels

Array dos 8 principais nomes de modelos por uso, para legendas de gráficos.

byKey

Detalhamento de uso por chave de API, ordenado por gasto total (do maior para o menor).

apiKeyId: O ID da chave de API ou nulo se o uso foi pelo aplicativo web
description: Descrição da chave de API ou “Web App”
totalUsd: Total em USD gasto por meio desta chave
totalDiem: Total em DIEM gasto por meio desta chave
totalUnits: Total de unidades consumidas por meio desta chave

byKeyDaily

Dados diários de gráfico para as 8 principais chaves de API. Cada entrada contém uma “date” (timestamp) mais descrições de chaves como chaves com valores de uso em DIEM.

topKeyNames

Array das 8 principais descrições de chaves de API por uso, para legendas de gráficos.

Exemplo de uso

# Obter análises de uso dos últimos 7 dias (padrão)
curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Obter análises de uso dos últimos 30 dias
curl -X GET "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Obter análises de uso para um intervalo de datas específico
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"

Autorizações

Authorization

string

header

obrigatório

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

Parâmetros de consulta

lookback

string

padrão:7d

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

Pattern: ^[1-9]\d*d$

Exemplo:

"7d"

startDate

string

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

Pattern: ^\d{4}-\d{2}-\d{2}$

Exemplo:

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

Exemplo:

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

Resposta

Successful response with aggregated usage analytics

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

lookback

string

obrigatório

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

Exemplo:

"7d"

byDate

object[]

obrigatório

Daily usage totals for the requested period

Show child attributes

byModel

object[]

obrigatório

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

Show child attributes

byModelDaily

object[]

obrigatório

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

Show child attributes

topModels

string[]

obrigatório

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

byKey

object[]

obrigatório

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

Show child attributes

byKeyDaily

object[]

obrigatório

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

Show child attributes

topKeyNames

string[]

obrigatório

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

⌘I

/api/v1/billing/usage-analytics

curl --request GET \
  --url https://api.venice.ai/api/v1/billing/usage-analytics \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.venice.ai/api/v1/billing/usage-analytics', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.venice.ai/api/v1/billing/usage-analytics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.venice.ai/api/v1/billing/usage-analytics"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.venice.ai/api/v1/billing/usage-analytics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

{
  "error": "<string>",
  "details": {
    "_errors": [],
    "field": {
      "_errors": [
        "Field is required"
      ]
    }
  }
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Venice APIs

Análise de uso de cobrança (Beta)

Parâmetros de consulta

Campos de resposta

lookback

byDate

byModel

byModelDaily

topModels

byKey

byKeyDaily

topKeyNames

Exemplo de uso

Autorizações

Parâmetros de consulta

Resposta

​Parâmetros de consulta

​Campos de resposta

​lookback

​byDate

​byModel

​byModelDaily

​topModels

​byKey

​byKeyDaily

​topKeyNames

​Exemplo de uso

Autorizações

Parâmetros de consulta

Resposta

Parâmetros de consulta

Campos de resposta

lookback

byDate

byModel

byModelDaily

topModels

byKey

byKeyDaily

topKeyNames

Exemplo de uso