Subscription

Query Subscription and Credit Balance

GET /v1/user/subscription

Query account credits, subscription status, and related metadata.

Request example:

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)

Response example:

{
  "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"
      }
    }
  }
}

Response fields:

All timestamps are 13-digit epoch-millisecond numbers. Fields tied to a plan (subscriptionStartedAt, subscriptionExpiresAt, subscriptionPlan.*) are only populated while a subscription is active; on a free account subscriptionPlan is {}.

Field	Type	Description
`totalAvailableCredits`	integer	Total credits you can spend right now: monthly + permanent + time-limited
`usageAvailableMonthlyCredits`	integer	Monthly credits remaining this cycle
`usageTotalMonthlyCredits`	integer	Monthly credit allotment for the cycle
`usageAvailablePermanentCredits`	integer	Permanent credits remaining (do not reset)
`usageTotalPermanentCredits`	integer	Total permanent credits granted
`usageAvailableLimitedTimeCredits`	integer	Time-limited credits remaining
`resetAt`	integer	When monthly credits reset (epoch ms)
`subscriptionStartedAt`	integer	Subscription start time (epoch ms)
`subscriptionExpiresAt`	integer	Subscription expiration time (epoch ms)
`platform`	string	Billing platform, e.g. `web`, `ios`, `android`. Defaults to `web`
`renewStatus`	boolean	Whether auto-renew is on
`paidStatus`	boolean	Whether the subscription is a paid (non-trial) active plan
`subscriptionPlan`	object	Active plan details, or `{}` when no plan is active
`subscriptionPlan.name`	string	Plan name, e.g. `pro`, `max`
`subscriptionPlan.duration`	string	Billing cycle, e.g. `monthly`, `yearly`
`subscriptionPlan.platform`	string	Platform the plan was purchased on
`freeUsages`	object	Free-quota balances keyed by resource key (see below)

Each freeUsages entry has the following shape:

Field	Type	Description
`remaining`	integer	Free generations left for this resource
`resourceType`	string	Resource category, e.g. `image`
`resourceKey`	string	The model/resource identifier (matches the map key)
`unit`	string	Unit of the quota, e.g. `generation`

API key calls draw down freeUsages before any credits are spent.

Free Quota (`freeUsages`)

API key calls consume the same account-level free-quota balance shown here as the web and Labnana apps. Your account can earn free quota through sign-up, invites, and check-ins; calling the API does not grant a separate allowance.

Resource key	Model	Sizes	Notes
`gemini-3-pro-image-relax-1k-2k`	NanoBanana Pro (relax)	`1K` / `2K` only	The headline free benefit. `4K` never draws from this balance.
`wan2.7-image`	Wan 2.7	`1K` / `2K` only	Bonus free quota.
`gpt-image-2`	GPT-Image-2	`1K` / `2K` only	Bonus free quota.

When freeUsages[<key>].remaining > 0, a matching 1K/2K generation through your API key spends the free quota instead of credits. Once it reaches 0, the same request falls back to ordinary credit billing. 4K always uses credits.

NanoBanana Pro free quota can keep refilling through sign-up, invites, and check-ins — it does not mean unlimited API calls. The balance is finite at any moment, and how a Pro relax call runs depends on your account type (see Image Generation → NanoBanana Pro Free Quota).

618 Campaign (Pro / Max monthly credits)

From 2026-06-18 through 2026-06-24 (Asia/Shanghai), active Pro and Max subscribers receive +50% monthly credits for their eligible membership cycle. Both monthly and annual billing participate; a Max subscriber's bonus is based on Max's own monthly credit amount.

The 618 bonus is a one-week boost to your monthly credits (usageTotalMonthlyCredits / usageAvailableMonthlyCredits). It is not a permanent plan upgrade, not a NanoBanana Pro free-quota (freeUsages) allowance, and not an upfront annual lump sum. The bonus resets with your current membership month, the same as ordinary monthly credits.

Query Subscription and Credit Balance

Free Quota (freeUsages)

618 Campaign (Pro / Max monthly credits)

On this page

Free Quota (`freeUsages`)