واجهة الاستعلام عن رصيد الحساب

آخر تحديث 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، يبقى الاستعلام عن الرصيد مسموحاً.
• المفاتيح المعطَّلة أو المنتهية الصلاحية لا يمكنها الاستعلام.
• لا تُعيد الواجهة USD أو CNY أو $ أو ¥، بل تستخدم yuan دائماً لتجنّب سوء الفهم.