サブスクリプション

アカウントのサブスクリプション状態、クレジット残高、有効期限を照会します。

サブスクリプションとクレジット残高を照会する

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	モデル / リソースの識別子（マップのキーと一致）
`unit`	string	枠の単位（例：`generation`）

API キーからの呼び出しは、クレジットを消費する前にまず freeUsages から差し引かれます。

無料枠（`freeUsages`）

API キーからの呼び出しは、Web アプリや 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 キー経由で対応する 1K/2K の生成を行うと、クレジットではなく無料枠が消費されます。0 になると、同じリクエストは通常のクレジット課金にフォールバックします。4K は常にクレジットを使用します。

NanoBanana Pro の無料枠は、新規登録・招待・チェックインを通じて継続的に補充できますが、API を無制限に呼び出せるという意味ではありません。残高はどの時点でも有限であり、Pro relax 呼び出しがどのように実行されるかはアカウントの種類によって決まります（画像生成 → NanoBanana Pro 無料枠を参照）。

618 キャンペーン（Pro / Max の月次クレジット）

2026-06-18 から 2026-06-24 まで（Asia/Shanghai）、有効な Pro および Max のサブスクライバーは、対象の会員サイクルについて 月次クレジット +50% を受け取れます。月次課金・年次課金のいずれも対象です。Max のサブスクライバーの加算は、Max 自身の月次クレジット量を基準に計算されます。

618 の加算は月次クレジット（usageTotalMonthlyCredits / usageAvailableMonthlyCredits）に対する 1 週間限定のブーストです。永続的なプランのアップグレードではなく、NanoBanana Pro の無料枠（freeUsages）の付与でもなく、年次課金の一括前払い分でもありません。加算分は通常の月次クレジットと同様に、現在の会員月とともにリセットされます。