구독 - ListenHub OpenAPI

구독 및 크레딧 잔액 조회

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자리 epoch 밀리초 숫자입니다. 플랜에 연동된 필드(subscriptionStartedAt, subscriptionExpiresAt, subscriptionPlan.*)는 구독이 활성 상태일 때만 값이 채워지며, 무료 계정에서는 subscriptionPlan이 {}입니다.

필드	타입	설명
`totalAvailableCredits`	integer	지금 바로 사용할 수 있는 총 크레딧: 월간 + 영구 + 기간 한정
`usageAvailableMonthlyCredits`	integer	이번 주기에 남은 월간 크레딧
`usageTotalMonthlyCredits`	integer	해당 주기의 월간 크레딧 지급량
`usageAvailablePermanentCredits`	integer	남은 영구 크레딧(리셋되지 않음)
`usageTotalPermanentCredits`	integer	지급된 영구 크레딧 총량
`usageAvailableLimitedTimeCredits`	integer	남은 기간 한정 크레딧
`resetAt`	integer	월간 크레딧이 리셋되는 시각(epoch ms)
`subscriptionStartedAt`	integer	구독 시작 시각(epoch ms)
`subscriptionExpiresAt`	integer	구독 만료 시각(epoch ms)
`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 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 호출이 어떻게 실행되는지는 계정 유형에 따라 달라집니다(이미지 생성 → 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) 지급도 아니고, 연간 결제의 선지급 일시금도 아닙니다. 보너스는 일반 월간 크레딧과 마찬가지로 현재 멤버십 월과 함께 리셋됩니다.

구독

구독 및 크레딧 잔액 조회

무료 할당량(freeUsages)

618 캠페인(Pro / Max 월간 크레딧)

이 페이지의 내용

무료 할당량(`freeUsages`)