> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Consulter le solde de l'utilisateur

>  - Consulter les crédits restants et utilisés globaux du compte utilisateur
- Obtenir les informations de solde au niveau utilisateur
- Prise en charge CORS pour les requêtes cross-origin
- Surveillance du solde en temps réel 

Obtenez le solde restant et le solde utilisé du compte utilisateur actuel. Cet endpoint renvoie les informations de solde au niveau utilisateur, indépendamment des tokens spécifiques, afin de consulter le solde global du compte.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://gccai.heqingsong.uk/v1/user/balance' \
    --header 'Authorization: Bearer <token>'
  ```

  ```python Python theme={null}
  import requests

  API_BASE = 'https://gccai.heqingsong.uk'
  API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx'

  headers = {
      'Authorization': f'Bearer {API_KEY}'
  }

  def get_user_balance():
      response = requests.get(f'{API_BASE}/v1/user/balance', headers=headers)
      data = response.json()
      
      if data.get('success'):
          print(f"Remaining balance: {data['remain_balance']}")
          print(f"Used balance: {data['used_balance']}")
      else:
          print(f"Query failed: {data.get('message')}")
      
      return data

  get_user_balance()
  ```

  ```javascript JavaScript theme={null}
  const API_BASE = 'https://gccai.heqingsong.uk';
  const API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxx';

  async function getUserBalance() {
    const response = await fetch(`${API_BASE}/v1/user/balance`, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    });
    
    const data = await response.json();
    
    if (data.success) {
      console.log(`Remaining balance: ${data.remain_balance}`);
      console.log(`Used balance: ${data.used_balance}`);
    } else {
      console.error('Query failed:', data.message);
    }
    
    return data;
  }

  getUserBalance();
  ```

  ```go Go theme={null}
  package main

  import (
      "encoding/json"
      "fmt"
      "io/ioutil"
      "net/http"
  )

  type BalanceResponse struct {
      Success        bool    `json:"success"`
      Message        string  `json:"message,omitempty"`
      RemainBalance  float64 `json:"remain_balance"`
      UsedBalance    float64 `json:"used_balance"`
  }

  func main() {
      url := "https://gccai.heqingsong.uk/v1/user/balance"

      req, _ := http.NewRequest("GET", url, nil)
      req.Header.Set("Authorization", "Bearer <token>")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, _ := ioutil.ReadAll(resp.Body)
      
      var result BalanceResponse
      json.Unmarshal(body, &result)
      
      if result.Success {
          fmt.Printf("Remaining balance: %.2f\n", result.RemainBalance)
          fmt.Printf("Used balance: %.2f\n", result.UsedBalance)
      }
  }
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  public class Main {
      public static void main(String[] args) throws Exception {
          String url = "https://gccai.heqingsong.uk/v1/user/balance";

          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(url))
              .header("Authorization", "Bearer <token>")
              .GET()
              .build();

          HttpResponse<String> response = client.send(request,
              HttpResponse.BodyHandlers.ofString());

          System.out.println(response.body());
      }
  }
  ```

  ```php PHP theme={null}
  <?php

  $api_key = 'sk-xxxxxxxxxxxxxxxxxxxxxx';

  $ch = curl_init('https://gccai.heqingsong.uk/v1/user/balance');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer $api_key"
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);

  if ($data['success']) {
      echo "Remaining balance: " . $data['remain_balance'] . "\n";
      echo "Used balance: " . $data['used_balance'] . "\n";
  } else {
      echo "Query failed: " . $data['message'] . "\n";
  }
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  api_key = 'sk-xxxxxxxxxxxxxxxxxxxxxx'

  url = URI("https://gccai.heqingsong.uk/v1/user/balance")

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

  request = Net::HTTP::Get.new(url)
  request["Authorization"] = "Bearer #{api_key}"

  response = http.request(request)
  data = JSON.parse(response.body)

  if data['success']
    puts "Remaining balance: #{data['remain_balance']}"
    puts "Used balance: #{data['used_balance']}"
  else
    puts "Query failed: #{data['message']}"
  end
  ```

  ```swift Swift theme={null}
  import Foundation

  let apiKey = "sk-xxxxxxxxxxxxxxxxxxxxxx"
  let url = URL(string: "https://gccai.heqingsong.uk/v1/user/balance")!

  var request = URLRequest(url: url)
  request.httpMethod = "GET"
  request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")

  let task = URLSession.shared.dataTask(with: request) { data, response, error in
      if let error = error {
          print("Error: \(error)")
          return
      }
      
      if let data = data, let responseString = String(data: data, encoding: .utf8) {
          print(responseString)
      }
  }

  task.resume()
  ```

  ```csharp C# theme={null}
  using System;
  using System.Net.Http;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main(string[] args)
      {
          var apiKey = "sk-xxxxxxxxxxxxxxxxxxxxxx";
          var url = "https://gccai.heqingsong.uk/v1/user/balance";

          using var client = new HttpClient();
          client.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");

          var response = await client.GetAsync(url);
          var result = await response.Content.ReadAsStringAsync();

          Console.WriteLine(result);
      }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "success": true,
    "remain_balance": 100.0,
    "remain_credits": 1000,
    "used_balance": 25.5,
    "used_credits": 255
  }
  ```

  ```json 200 - User Quota Query Failed theme={null}
  {
    "success": false,
    "message": "Failed to get user quota: record not found"
  }
  ```

  ```json 200 - Used Quota Query Failed theme={null}
  {
    "success": false,
    "message": "Failed to get used quota: record not found"
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Invalid authentication credentials",
      "type": "authentication_error"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Rate limit exceeded. Please try again later",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## Autorisation

<ParamField header="Authorization" type="string" required>
  Tous les endpoints API requièrent une authentification par Bearer Token

  Obtenez votre clé API :

  Rendez-vous sur la [page de gestion des clés API](https://gccai.heqingsong.uk/keys) pour obtenir votre clé API

  Ajoutez-la à l'en-tête de la requête :

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Endpoints

```
GET /v1/user/balance
GET /user/balance
```

Les deux endpoints offrent les mêmes fonctionnalités ; vous pouvez utiliser l'un ou l'autre.

## Réponse

<ResponseField name="success" type="boolean">
  Indique si la requête a réussi
</ResponseField>

<ResponseField name="message" type="string">
  Message d'erreur (renvoyé uniquement en cas d'échec)
</ResponseField>

<ResponseField name="remain_balance" type="float">
  Solde restant de l'utilisateur (renvoyé en cas de succès)
</ResponseField>

<ResponseField name="remain_credits" type="integer">
  Crédits restants de l'utilisateur (renvoyé en cas de succès)
</ResponseField>

<ResponseField name="used_balance" type="float">
  Solde utilisé de l'utilisateur (renvoyé en cas de succès)
</ResponseField>

<ResponseField name="used_credits" type="float">
  Crédits utilisés de l'utilisateur (renvoyé en cas de succès)
</ResponseField>

## Solde du token vs solde utilisateur

| Comparaison        | Solde du token (`/v1/balance`)         | Solde utilisateur (`/v1/user/balance`) |
| ------------------ | -------------------------------------- | -------------------------------------- |
| Portée             | Un seul token                          | Compte utilisateur complet             |
| Source des données | RemainQuota et UsedQuota du token      | quota et used\_quota de l'utilisateur  |
| Cas d'usage        | Surveiller l'utilisation d'une clé API | Consulter le solde global du compte    |
| Limité par         | Limites de quota au niveau du token    | Limites de quota au niveau utilisateur |

## Cas d'usage

* Consulter le solde global du compte utilisateur
* Configurer des rappels de recharge et des alertes de solde
* Afficher le solde du compte dans le tableau de bord utilisateur

<Note>
  **Informations sur l'unité du solde**

  L'unité de la valeur du solde dépend de la configuration du système :

  * **USD** — Dollars américains
  * **CNY** — Yuans chinois
  * **Tokens** — Nombre de tokens
</Note>

## Erreurs fréquentes

| Message d'erreur         | Cause                                | Solution                                                   |
| ------------------------ | ------------------------------------ | ---------------------------------------------------------- |
| No Authorization header  | En-tête Authorization non fourni     | Ajoutez l'en-tête `Authorization: Bearer sk-xxxxx`         |
| Failed to get user quota | L'utilisateur n'existe pas           | Vérifiez que l'utilisateur associé au token existe         |
| Failed to get used quota | Erreur de requête en base de données | Contactez l'administrateur pour vérifier l'état du système |

<Warning>
  **Note de sécurité**

  Votre clé API est comme un mot de passe. Conservez-la en sécurité et ne la partagez pas. Utilisez toujours HTTPS en production.
</Warning>