API استعلام موجودی حساب

به‌روزرسانی 2026-09-18 · تیم Suno-API

توضیح نقطه پایانی

استعلام موجودی حساب به کاربر امکان می‌دهد موجودی حساب New API خود را با کلید API خودش بررسی کند. این نقطه پایانی فقط موجودی را استعلام می‌کند؛ کار تولیدی ایجاد نمی‌کند و هزینه‌ای هم نمی‌گیرد.

نقطه پایانی: GET /api/user/balance

صورت‌حساب: رایگان.

واحد موجودی: yuan. در پاسخ، مقدار effective_amount با quota_per_unit به مبلغ یوانی قابل فهم برای کاربر تبدیل شده است.

پارامترهای درخواست

Headers

پارامترهای کوئری

هیچ.

نمونه‌های درخواست

cURL

curl -X GET https://www.suno-api.io/api/user/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

api_key = "YOUR_API_KEY"
response = requests.get(
    "https://www.suno-api.io/api/user/balance",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30,
)
response.raise_for_status()

result = response.json()
balance = result["data"]["balance"]
print(balance["formatted_effective_amount"])

Node.js

const apiKey = "YOUR_API_KEY";

const response = await fetch("https://www.suno-api.io/api/user/balance", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const result = await response.json();
console.log(result.data.balance.formatted_effective_amount);

PHP

<?php
$apiKey = "YOUR_API_KEY";

$ch = curl_init("https://www.suno-api.io/api/user/balance");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $apiKey
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
if ($response === false) {
    throw new Exception(curl_error($ch));
}
curl_close($ch);

$result = json_decode($response, true);
echo $result["data"]["balance"]["formatted_effective_amount"];
?>

پاسخ

{
  "success": true,
  "message": "",
  "data": {
    "object": "user_balance",
    "user": {
      "id": 123,
      "username": "example",
      "quota": 207900000,
      "used_quota": 0,
      "request_count": 10,
      "group": "default",
      "status": 1
    },
    "token": {
      "id": 456,
      "name": "default",
      "group": "default",
      "status": 1,
      "remain_quota": 207900000,
      "used_quota": 0,
      "unlimited_quota": true,
      "model_limits_enabled": false,
      "model_limits": {}
    },
    "balance": {
      "user_quota": 207900000,
      "token_quota": 207900000,
      "effective_quota": 207900000,
      "user_amount": 415.8,
      "token_amount": 415.8,
      "effective_amount": 415.8,
      "amount_unit": "yuan",
      "formatted_effective_amount": "415.80 yuan"
    },
    "display": {
      "quota_per_unit": 500000,
      "amount_unit": "yuan"
    }
  }
}

مرجع فیلدها

نکات

• این نقطه پایانی از همان کلید API نقاط پایانی تولید استفاده می‌کند.
• حتی وقتی موجودی کلید API تمام شده باشد، استعلام موجودی مجاز است.
• کلیدهای API غیرفعال یا منقضی نمی‌توانند استعلام کنند.
• این نقطه پایانی USD، CNY، $ یا ¥ برنمی‌گرداند و همیشه از yuan استفاده می‌کند تا سوءتفاهم پیش نیاید.