StarWing API 文档

面向中继模式的最小接入说明，覆盖鉴权、余额查询、图像生成和常见错误返回。

接入前准备

  1. 注册并登录控制台。
  2. 在“API 密钥”页创建 App-Token。
  3. 按需要配置有效期、额度、RPM、并发和 IP 白名单。
  4. 使用 `Authorization: Bearer <你的 App-Token>` 调用接口。
API Base URL: https://www.xzyai.top

权限与限流

  • Basic 默认 RPM / 日限额: 10 / 100 点/日
  • Advanced 默认 RPM / 日限额: 50 / 500 点/日
  • Basic 默认可用模型：gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, gemini-2.5-flash-image
  • Advanced 默认可用模型：gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, gemini-2.5-flash-image, imagen-4.0-generate-001, imagen-4.0-fast-generate-001
  • 余额接口还会返回客户端能力清单，包括分辨率上限、上采样算法、模板范围和并行请求数。
  • Token 级别可继续叠加总额度、日额度、月额度、RPM、并发限制。
  • Token 可设置过期时间和 IP 白名单。

支持模型与点数

模型单次消耗最低版本
gemini-2.5-flash-image 1 点 Basic
gemini-3-pro-image-preview 5 点 Basic
gemini-3.1-flash-image-preview 1 点 Basic
imagen-4.0-fast-generate-001 8 点 Advanced
imagen-4.0-generate-001 10 点 Advanced

1. 查询账户余额

`GET /v1/credits/balance`
curl "https://www.xzyai.top/v1/credits/balance" ^
  -H "Authorization: Bearer YOUR_APP_TOKEN"
{
  "balance": 320,
  "total_recharged": 500,
  "total_consumed": 180,
  "tier": "basic",
  "daily_limit": 100,
  "daily_used": 8,
  "rpm_limit": 10,
  "allowed_models": [
    "gemini-3.1-flash-image-preview",
    "gemini-3-pro-image-preview",
    "gemini-2.5-flash-image"
  ],
  "client_capabilities": {
    "edition_label": "Basic",
    "max_resolution": "2K (1920px)",
    "supports_custom_resolution": false,
    "upscale_algorithms": ["Bilinear", "Nearest"],
    "preset_scope": "标准预设模板",
    "parallel_requests": 1
  },
  "token": {
    "name": "Default",
    "group_name": "default",
    "quota_limit": 0,
    "daily_quota_limit": 0,
    "monthly_quota_limit": 0,
    "rpm_limit": 10,
    "concurrency_limit": 1,
    "total_used": 30,
    "daily_used": 8,
    "monthly_used": 120,
    "active_requests": 0
  }
}

2. 生成图像

`POST /v1/generate`
curl "https://www.xzyai.top/v1/generate" ^
  -H "Authorization: Bearer YOUR_APP_TOKEN" ^
  -H "Content-Type: application/json" ^
  -d "{
    \"model\": \"gemini-3.1-flash-image-preview\",
    \"contents\": [
      {
        \"parts\": [
          {\"text\": \"一张电影级霓虹夜景海报，赛博城市街头，雨夜反光\"}
        ]
      }
    ]
  }"
import requests

resp = requests.post(
    "https://www.xzyai.top/v1/generate",
    headers={
        "Authorization": "Bearer YOUR_APP_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "model": "gemini-3.1-flash-image-preview",
        "contents": [
            {
                "parts": [
                    {"text": "一张电影级霓虹夜景海报，赛博城市街头，雨夜反光"}
                ]
            }
        ],
    },
    timeout=120,
)
resp.raise_for_status()
print(resp.json())

常见错误码

error含义
missing_token缺少 Bearer Token
invalid_tokenToken 不存在
token_disabledToken 被停用
token_expiredToken 已过期
ip_not_allowed请求 IP 不在白名单
token_rate_limited命中 Token RPM 限制
token_concurrency_exceeded命中 Token 并发限制
daily_limit_exceeded命中账户日限额
tier_model_forbidden当前版本无权调用该模型
insufficient_balance点数不足
unsupported_model模型不支持

说明

  • 网关会按模型配置自动扣点，失败请求会回退余额。
  • 余额接口会返回当前版本的默认 RPM、日限额和可用模型列表，客户端可直接据此展示权限。
  • 支付完成后可在“兑换”页购买点数套餐，或使用兑换码充值。
  • 如需批量发码、企业额度或人工补偿，可通过工单系统联系运营。
  • 正式商户联调后，支付状态会通过回调和后台同步页共同收口。