订阅与余额

获取订阅详情与余额信息

GET /v1/user/subscription

查询账户的积分余额、订阅状态等信息。

请求示例：

curl -X GET "https://api.marswave.ai/openapi/v1/user/subscription" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

const response = await fetch(
  'https://api.marswave.ai/openapi/v1/user/subscription',
  {
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
    },
  },
)
const data = await response.json()
console.log(data)

import os
import requests

response = requests.get(
    'https://api.marswave.ai/openapi/v1/user/subscription',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'}
)
data = response.json()
print(data)

响应示例：

{
  "code": 0,
  "message": "",
  "data": {
    "subscriptionStartedAt": 1735660800000,
    "subscriptionExpiresAt": 1767196800000,
    "usageAvailableMonthlyCredits": 500,
    "usageTotalMonthlyCredits": 1000,
    "usageAvailablePermanentCredits": 300,
    "usageTotalPermanentCredits": 500,
    "usageAvailableLimitedTimeCredits": 200,
    "totalAvailableCredits": 1000,
    "resetAt": 1735660800000,
    "platform": "web",
    "renewStatus": false,
    "paidStatus": true,
    "subscriptionPlan": {
      "name": "pro",
      "duration": "monthly",
      "platform": "web"
    },
    "freeUsages": {
      "gemini-3-pro-image-relax-1k-2k": {
        "remaining": 2,
        "resourceType": "image",
        "resourceKey": "gemini-3-pro-image-relax-1k-2k",
        "unit": "generation"
      },
      "wan2.7-image": {
        "remaining": 1,
        "resourceType": "image",
        "resourceKey": "wan2.7-image",
        "unit": "generation"
      },
      "gpt-image-2": {
        "remaining": 1,
        "resourceType": "image",
        "resourceKey": "gpt-image-2",
        "unit": "generation"
      }
    }
  }
}

响应字段：

所有时间戳均为 13 位毫秒级数字。与套餐相关的字段（subscriptionStartedAt、subscriptionExpiresAt、subscriptionPlan.*）仅在订阅有效时才会填充；免费账户的 subscriptionPlan 为 {}。

字段	类型	说明
`totalAvailableCredits`	integer	当前总可用积分：月度 + 永久 + 限时
`usageAvailableMonthlyCredits`	integer	本周期剩余的月度积分
`usageTotalMonthlyCredits`	integer	本周期的月度积分额度
`usageAvailablePermanentCredits`	integer	剩余的永久积分（不重置）
`usageTotalPermanentCredits`	integer	已发放的永久积分总量
`usageAvailableLimitedTimeCredits`	integer	剩余的限时积分
`resetAt`	integer	月度积分重置时间（毫秒时间戳）
`subscriptionStartedAt`	integer	订阅开始时间（毫秒时间戳）
`subscriptionExpiresAt`	integer	订阅到期时间（毫秒时间戳）
`platform`	string	计费平台，如 `web`、`ios`、`android`，默认 `web`
`renewStatus`	boolean	是否开启自动续费
`paidStatus`	boolean	是否为付费（非试用）的有效订阅
`subscriptionPlan`	object	有效套餐信息，无有效套餐时为 `{}`
`subscriptionPlan.name`	string	套餐名称，如 `pro`、`max`
`subscriptionPlan.duration`	string	计费周期，如 `monthly`、`yearly`
`subscriptionPlan.platform`	string	购买套餐的平台
`freeUsages`	object	免费额度余额，以资源键为索引（见下文）

每个 freeUsages 条目的结构如下：

字段	类型	说明
`remaining`	integer	该资源剩余的免费生成次数
`resourceType`	string	资源类别，如 `image`
`resourceKey`	string	模型/资源标识符（与 map 的键一致）
`unit`	string	额度单位，如 `generation`

API Key 调用会优先扣除 freeUsages 余额，再消耗积分。

免费额度（`freeUsages`）

API Key 调用消耗的免费额度，和网页端、Labnana 是同一份账户级余额。账户可以通过注册、邀请、签到不断领取免费额度，调用 API 不会单独发放额度。

资源键	模型	尺寸	说明
`gemini-3-pro-image-relax-1k-2k`	NanoBanana Pro（relax）	仅 `1K` / `2K`	核心免费权益，`4K` 不会扣这份额度
`wan2.7-image`	Wan 2.7	仅 `1K` / `2K`	赠送的免费额度
`gpt-image-2`	GPT-Image-2	仅 `1K` / `2K`	赠送的免费额度

当 freeUsages[<key>].remaining > 0 时，通过 API Key 发起的对应 1K/2K 生成会扣免费额度而非积分；额度降到 0 后，同一请求会回退到常规积分计费。4K 始终走积分。

NanoBanana Pro 免费额度可以通过注册、邀请、签到持续领取，但并不代表 API 可以无限调用。任一时刻的余额都是有限的，且 Pro relax 调用的执行方式取决于账户类型（见 AI 生图 → NanoBanana Pro 免费额度）。

618 限时活动（Pro / Max 月度积分）

2026-06-18 至 2026-06-24（Asia/Shanghai）期间，有效的 Pro 和 Max 订阅用户，当前会员周期可获得 +50% 月度积分。月付、年付都参与；Max 的加赠按 Max 自身的月度积分额度计算。

618 加赠是对月度积分（usageTotalMonthlyCredits / usageAvailableMonthlyCredits）的限时一周加成，不是永久套餐升级，不是 NanoBanana Pro 免费额度（freeUsages）发放，也不是年付的一次性整年积分。加赠为月度积分，随当前会员月到期重置，行为与普通月度积分一致。

获取订阅详情与余额信息

免费额度（freeUsages）

618 限时活动（Pro / Max 月度积分）

On this page

免费额度（`freeUsages`）