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

# Nutzerguthaben abfragen

>  - Gesamtes verbleibendes und verbrauchtes Guthaben des Nutzerkontos abfragen
- Guthaben-Informationen auf Nutzerebene abrufen
- CORS-Unterstützung für Cross-Origin-Anfragen
- Guthabenüberwachung in Echtzeit 

Rufen Sie das verbleibende und das verbrauchte Guthaben des aktuellen Nutzerkontos ab. Dieser Endpunkt liefert Guthabeninformationen auf Nutzerebene, unabhängig von einzelnen Tokens, und dient zur Anzeige des Gesamtguthabens des Kontos.

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

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

  API_BASE = 'https://api.apimart.ai'
  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://api.apimart.ai';
  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://api.apimart.ai/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://api.apimart.ai/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://api.apimart.ai/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://api.apimart.ai/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://api.apimart.ai/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://api.apimart.ai/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>

## Autorisierung

<ParamField header="Authorization" type="string" required>
  Alle API-Endpunkte erfordern eine Authentifizierung per Bearer Token

  So erhalten Sie Ihren API-Key:

  Besuchen Sie die [API-Key-Verwaltungsseite](https://apimart.ai/keys), um Ihren API-Key zu erhalten

  Fügen Sie ihn dem Request-Header hinzu:

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

## Endpunkte

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

Beide Endpunkte haben dieselbe Funktionalität — Sie können einen davon nach Belieben verwenden.

## Antwort

<ResponseField name="success" type="boolean">
  Gibt an, ob die Anfrage erfolgreich war
</ResponseField>

<ResponseField name="message" type="string">
  Fehlermeldung (wird nur im Fehlerfall zurückgegeben)
</ResponseField>

<ResponseField name="remain_balance" type="float">
  Verbleibendes Guthaben des Nutzers (wird bei Erfolg zurückgegeben)
</ResponseField>

<ResponseField name="remain_credits" type="integer">
  Verbleibende Credits des Nutzers (wird bei Erfolg zurückgegeben)
</ResponseField>

<ResponseField name="used_balance" type="float">
  Verbrauchtes Guthaben des Nutzers (wird bei Erfolg zurückgegeben)
</ResponseField>

<ResponseField name="used_credits" type="float">
  Verbrauchte Credits des Nutzers (wird bei Erfolg zurückgegeben)
</ResponseField>

## Token-Guthaben vs. Nutzerguthaben

| Vergleich        | Token-Guthaben (`/v1/balance`)              | Nutzerguthaben (`/v1/user/balance`) |
| ---------------- | ------------------------------------------- | ----------------------------------- |
| Geltungsbereich  | Einzelner Token                             | Gesamtes Nutzerkonto                |
| Datenquelle      | RemainQuota und UsedQuota des Tokens        | quota und used\_quota des Nutzers   |
| Anwendungsfall   | Nutzung eines einzelnen API-Keys überwachen | Gesamtkontostand einsehen           |
| Beschränkt durch | Token-Kontingentgrenzen                     | Nutzer-Kontingentgrenzen            |

## Anwendungsfälle

* Gesamtguthaben des Nutzerkontos einsehen
* Aufladeerinnerungen und Guthabenwarnungen einrichten
* Kontostand im Nutzer-Dashboard anzeigen

<Note>
  **Hinweise zur Guthabeneinheit**

  Die Einheit des Guthabenwerts hängt von der Systemkonfiguration ab:

  * **USD** – US-Dollar
  * **CNY** – Chinesische Yuan
  * **Tokens** – Token-Anzahl
</Note>

## Häufige Fehler

| Fehlermeldung            | Ursache                              | Lösung                                                              |
| ------------------------ | ------------------------------------ | ------------------------------------------------------------------- |
| No Authorization header  | Authorization-Header nicht angegeben | Header `Authorization: Bearer sk-xxxxx` hinzufügen                  |
| Failed to get user quota | Nutzer existiert nicht               | Prüfen Sie, ob der zum Token gehörende Nutzer existiert             |
| Failed to get used quota | Fehler bei Datenbankabfrage          | Wenden Sie sich an den Administrator, um den Systemstatus zu prüfen |

<Warning>
  **Sicherheitshinweis**

  Ihr API-Key ist wie ein Passwort. Bewahren Sie ihn sicher auf und geben Sie ihn nicht an andere weiter. Verwenden Sie in Produktivumgebungen stets HTTPS.
</Warning>