Consultation et export de facturation

Les statistiques agrègent usage, appels et montants par intervalle. Les relevés Excel servent à la conservation et au contrôle hors ligne.

Préparer un jeton d’accès

Créez un jeton d’accès dans « Sécurité » de votre profil, puis saisissez-le dans Try It pour Consulter les statistiques ou Exporter la facturation.

Choisir la période et les filtres

Sélectionnez la granularité, par exemple « Jour » pour un total quotidien.
Saisissez les horodatages Unix en secondes, ou utilisez le sélecteur de dates à droite. Il utilise le fuseau local du navigateur ; pour une journée entière, vérifiez l’heure de fin.
Saisissez un nom uniquement pour cibler une clé ou un modèle ; laissez les deux champs vides pour tous les enregistrements correspondants.

Filtre	Obligatoire	Utilisation
Granularité `type`	Oui	1=minute, 2=heure, 3=jour, 4=semaine, 5=mois
Début et fin	Oui	`startTime`, `endTime` en secondes ; la fin ne précède pas le début
Nom d’API Key `tokenName`	Non	Nom, pas secret ni jeton d’accès ; omettre pour ne pas filtrer
Nom du modèle `modelName`	Non	Nom réel du modèle ; omettre pour ne pas filtrer

Consulter les résultats

Envoyez les filtres dans Try It de Consulter les statistiques. Le corps code=200 indique un succès métier ; data contient des agrégats, pas un journal de chaque appel.

time, timeGroup : heure du relevé et horodatage du groupe en secondes.
callCount, totalUseTime : nombre d’appels et durée totale.
totalPromptTokens, totalCompletionTokens et champs de cache : usage en entrée, sortie et cache.
totalAmount : montant consommé. Voir les champs et exemples dans la Reference ; ne confondez pas Tokens et montant.

code: 200 avec data: [] signifie une requête réussie sans résultat pour la période et les filtres.

Des champs facultatifs peuvent être null ; ne les traitez pas comme 0.

Exporter un relevé Excel

Envoyez les mêmes filtres dans Try It de Exporter la facturation. Une fois le fichier reçu :

Vérifiez la période d’export affichée.
Gardez le nom généré à partir de la période ou modifiez « Nom du fichier » ; .xlsx est conservé automatiquement.
Cliquez sur « Télécharger le relevé Excel » pour enregistrer localement.

Les dates du nom utilisent le fuseau du navigateur. Contenu et colonnes sont générés par la plateforme ; renommer ne les modifie pas. Comparez avec les mêmes période, granularité et filtres.

HTTP 200 ne garantit pas l’export : traitez les erreurs JSON au lieu de les enregistrer en .xlsx.

Dépannage

Symptôme	Action
Réussite sans données	Vérifier unités et dates, puis effacer les filtres de noms
Code métier `code: 401`, authentification échouée	Vérifier le jeton ; contacter le support si un jeton valide échoue encore
Export `code: 400`, validation échouée	Vérifier granularité, début et fin
Export `code: 500`, `ERROR`	Vérifier JSON et types ; contacter l’administrateur si les valeurs correctes échouent
Excel ne peut pas ouvrir le fichier	Vérifier Content-Type et l’absence d’erreur JSON enregistrée en Excel

Ces erreurs métier peuvent être renvoyées avec HTTP 200. Le statut HTTP seul ne suffit pas ; voir les exemples complets dans les References.

Consultez les tarifs actuels dans le catalogue de modèles.

Appeler depuis un programme

L’exemple Bash nécessite curl et jq, et couvre authentification, statistiques et sauvegarde Excel.

Assemblez les trois blocs suivants, dans l’ordre, dans un seul fichier .sh. Modifiez jeton et période, puis exécutez avec bash ; ne collez pas chaque bloc séparément dans un terminal interactif.

La période d’exemple va du 2026-10-10 00:00:00 au 2026-10-20 23:59:59, heure de Pékin, par jour et sans filtre de nom. Remplacez-la selon vos besoins.

1. Obtenir l’authentification de facturation

Avec le jeton d’accès, appelez GET /api/user/self, extrayez token de data.remark et utilisez-le pour les factures du même site. Le jeton d’accès sert au Bearer initial ; il ne remplace pas directement le Header de facturation token.

set -euo pipefail

ACCESS_TOKEN='your-user-token'

BILLING_TOKEN=$(curl --fail --silent --show-error "https://api.agtcloud.cn/api/user/self" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | \
  jq -er '
    select(.success == true)
    | .data.remark | fromjson | .token
    | select(type == "string" or type == "number")
    | tostring | select(length > 0)
  ')

2. Consulter les statistiques

curl --fail-with-body "https://api.agtcloud.cn/bill/stats" \
  -X POST \
  -H "token: ${BILLING_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": 3,
    "startTime": 1791561600,
    "endTime": 1792511999
  }'

Vérifiez le code JSON, pas seulement la sortie de cURL. Le timestamp racine est en millisecondes, contrairement aux périodes en secondes.

3. Valider et enregistrer Excel

La réussite doit être un flux application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, pas une erreur métier JSON.

Écrivez d’abord dans un fichier temporaire ; enregistrez bill_export.xlsx seulement avec HTTP 200, un type Excel et un fichier non vide. Aucun fichier existant n’est écrasé.

response_file=$(mktemp './.bill_export.XXXXXX')
[[ "$response_file" == ./.bill_export.* && -f "$response_file" && ! -L "$response_file" ]] || exit 1
trap 'if [[ "$response_file" == ./.bill_export.* && -f "$response_file" && ! -L "$response_file" ]]; then rm -f -- "$response_file"; fi' EXIT

response_meta=$(curl --silent --show-error "https://api.agtcloud.cn/bill/excel" \
  -X POST \
  -H "token: ${BILLING_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": 3,
  "startTime": 1791561600,
  "endTime": 1792511999
}' \
  --output "$response_file" \
  --write-out '%{http_code}\n%{content_type}')

http_status=${response_meta%%$'\n'*}
content_type=${response_meta#*$'\n'}
if [[ "$http_status" != 200 || "${content_type%%;*}" != application/vnd.openxmlformats-officedocument.spreadsheetml.sheet || ! -s "$response_file" ]]; then
  printf 'Export failed: HTTP %s (%s)\n' "$http_status" "$content_type" >&2
  if [[ "${content_type%%;*}" == application/json ]]; then
    jq '{code, message}' "$response_file" >&2
  fi
  exit 1
fi

if [[ -e bill_export.xlsx || -L bill_export.xlsx ]]; then
  printf 'bill_export.xlsx already exists; choose another filename.\n' >&2
  exit 1
fi
mv -n -- "$response_file" bill_export.xlsx
if [[ -e "$response_file" ]]; then
  printf 'bill_export.xlsx already exists; choose another filename.\n' >&2
  exit 1
fi
printf 'Saved bill_export.xlsx\n'