余额与订阅额度
GET /v1/account/balance 查询当前 API Key 所属账户。GET /api/account/balance 是等效路径。两个路径均接受 Authorization: Bearer 或 x-api-key。无需请求体,查询不改变账户余额、不消耗订阅额度,也不计入调用记录。
bash
curl 'https://modelfold.ai/v1/account/balance' \
-H "Authorization: Bearer $MODELFOLD_API_KEY"python
import os
import requests
resp = requests.get(
"https://modelfold.ai/v1/account/balance",
headers={
"Authorization": "Bearer " + os.environ["MODELFOLD_API_KEY"],
},
)
print(resp.json())javascript
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());go
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))
}java
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
<?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);csharp
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());bash
curl 'https://modelfold.ai/api/account/balance' \
-H "x-api-key: $MODELFOLD_API_KEY"python
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())javascript
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());go
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))
}java
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
<?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);csharp
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());返回示例(节选):
json
{
"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:账户剩余点数(JSON 数字),不含订阅额度。subscription:没有生效订阅时只返回{ "active": false }。有订阅时返回套餐的中英文名称、到期时间expiresAt、5 小时窗口window和本周周期week。total/used/remaining:该订阅周期的总量、已用和剩余,与用户中心使用同一计算口径。usedPercent单位为百分比(20表示 20%);如果最后一次调用超出额度,剩余返回0。resetAt/expiresAt:Unix 毫秒时间戳。5 小时窗口未开启时,window.resetAt为null;下一次符合订阅规则的模型调用才会开启新窗口。keyQuota:仅针对当前 Key。设有限额时返回limit(上限)、used(已用)和remaining(剩余,最低为0);未设上限时为null。
错误类型在 error.type:Key 缺失、无效或已吊销返回 401(invalid_api_key);账号停用或 IP 不在白名单返回 403(account_restricted 或 ip_not_allowed);查询过于频繁返回 429(rate_limited),请按 Retry-After 稍后重试。
在 Agent 工具里使用
查询地址固定是 https://modelfold.ai/v1/account/balance。Key 就用你在 Claude Code、Codex、Cursor、Cline 等 Agent 工具里配置的同一个 ModelFold API Key,不需要另外创建查询专用的 Key。
- Claude Code:把上面的 curl 命令交给它执行,或在状态栏脚本(statusLine)里调用,随时显示剩余点数和订阅额度。Claude Code 发送的
x-api-key请求头同样被接受。 - Codex 等 OpenAI 格式的工具:Base URL 一般配置为
https://modelfold.ai/v1,查询地址就是 Base URL 后面接/account/balance。 - 查询本身不消耗点数,但有频率限制(每 10 分钟 60 次),状态栏脚本建议缓存 1 分钟以上。
