Balance and subscription quota
GET /v1/account/balance returns balances for the account that owns the supplied API key. GET /api/account/balance is an alias. Both endpoints accept Authorization: Bearer or x-api-key. No request body is needed. The query does not change the account balance, consume subscription quota, or count as a model call.
curl 'https://modelfold.ai/v1/account/balance' \
-H "Authorization: Bearer $MODELFOLD_API_KEY"import os
import requests
resp = requests.get(
"https://modelfold.ai/v1/account/balance",
headers={
"Authorization": "Bearer " + os.environ["MODELFOLD_API_KEY"],
},
)
print(resp.json())const resp = await fetch("https://modelfold.ai/v1/account/balance", {
method: "GET",
headers: {
"Authorization": "Bearer " + process.env.MODELFOLD_API_KEY,
},
});
console.log(await resp.json());package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, _ := http.NewRequest("GET", "https://modelfold.ai/v1/account/balance", nil)
req.Header.Set("Authorization", "Bearer " + os.Getenv("MODELFOLD_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(string(out))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://modelfold.ai/v1/account/balance"))
.header("Authorization", "Bearer " + System.getenv("MODELFOLD_API_KEY"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());
}
}<?php
$ch = curl_init('https://modelfold.ai/v1/account/balance');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv("MODELFOLD_API_KEY"),
],
]);
echo curl_exec($ch);
curl_close($ch);using System;
using System.Net.Http;
using System.Text;
var client = new HttpClient();
var req = new HttpRequestMessage(new HttpMethod("GET"), "https://modelfold.ai/v1/account/balance");
req.Headers.TryAddWithoutValidation("Authorization", "Bearer " + Environment.GetEnvironmentVariable("MODELFOLD_API_KEY"));
var resp = await client.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());curl 'https://modelfold.ai/api/account/balance' \
-H "x-api-key: $MODELFOLD_API_KEY"import os
import requests
resp = requests.get(
"https://modelfold.ai/api/account/balance",
headers={
"x-api-key": os.environ["MODELFOLD_API_KEY"],
},
)
print(resp.json())const resp = await fetch("https://modelfold.ai/api/account/balance", {
method: "GET",
headers: {
"x-api-key": process.env.MODELFOLD_API_KEY,
},
});
console.log(await resp.json());package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, _ := http.NewRequest("GET", "https://modelfold.ai/api/account/balance", nil)
req.Header.Set("x-api-key", os.Getenv("MODELFOLD_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(string(out))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://modelfold.ai/api/account/balance"))
.header("x-api-key", System.getenv("MODELFOLD_API_KEY"))
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> resp = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());
}
}<?php
$ch = curl_init('https://modelfold.ai/api/account/balance');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'x-api-key: ' . getenv("MODELFOLD_API_KEY"),
],
]);
echo curl_exec($ch);
curl_close($ch);using System;
using System.Net.Http;
using System.Text;
var client = new HttpClient();
var req = new HttpRequestMessage(new HttpMethod("GET"), "https://modelfold.ai/api/account/balance");
req.Headers.TryAddWithoutValidation("x-api-key", Environment.GetEnvironmentVariable("MODELFOLD_API_KEY"));
var resp = await client.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());Example response (excerpt):
{
"ok": true,
"subscription": {
"active": true,
"plan": { "nameZh": "示例套餐", "nameEn": "Example plan" },
"expiresAt": 1802000000000,
"window": { "total": 100, "used": 20, "remaining": 80, "usedPercent": 20, "resetAt": 1800000000000 },
"week": { "total": 800, "used": 60, "remaining": 740, "usedPercent": 7.5, "resetAt": 1800500000000 }
},
"keyQuota": { "limit": 50, "used": 12.5, "remaining": 37.5 }
}credits: Remaining account balance (a JSON number), separate from subscription quota.subscription: Returns only{ "active": false }when there is no active subscription. Otherwise it includes the plan's Chinese and English names, its expiration timeexpiresAt, the five-hourwindow, and the currentweek.total/used/remaining: Subscription quota for the period, calculated using the same rules as the account dashboard.usedPercentis a percentage (20means 20%). If the last call exceeded the quota,remainingis0.resetAt/expiresAt: Unix timestamps in milliseconds.window.resetAtisnullwhen no five-hour window is open. The next qualifying model call opens a new window.keyQuota: Applies only to the supplied key. If the key has a credit limit, this field containslimit,used, andremaining(never below0). Otherwise it isnull.
See error.type for the error code. Missing, invalid, or revoked keys return 401 (invalid_api_key). Restricted accounts and disallowed source IPs return 403 (account_restricted or ip_not_allowed). Rate-limited requests return 429 (rate_limited); follow the Retry-After header before retrying.
Using it in agent tools
The endpoint is always https://modelfold.ai/v1/account/balance. Use the same ModelFold API key you configured in Claude Code, Codex, Cursor, Cline or other agent tools; you do not need a separate key for balance queries.
- Claude Code: ask it to run the curl command above, or call the endpoint from a statusLine script to show your remaining balance and subscription quota. The
x-api-keyheader that Claude Code sends is accepted. - Codex and other OpenAI-compatible tools: the base URL is usually
https://modelfold.ai/v1, so the balance URL is the base URL followed by/account/balance. - Queries are free but rate limited (60 per 10 minutes). Cache the result for at least a minute in status-bar scripts.
