XAPI 免费服务上手指南

您可以将 XAPI 简单理解为：一个开箱即用的开发者后端工具箱。

它提供了一系列通用的后端 API 服务，旨在让您无需编写一行后端代码，即可为您的应用快速集成动态内容、数据统计、二维码生成、文件存储等功能。您只需专注于您的核心业务和前端开发，XAPI 负责提供稳定、高性能的底层支持。

统一 API 入口：所有服务均通过 api.xabcstack.com 提供，管理接口统一使用 XAPI KEY，接口设计遵循 RESTful 风格，简洁易用。
高性能架构：内置多级缓存（内存、Redis），确保高并发下的毫秒级响应，为您的应用提供流畅体验。
事件驱动设计：服务间通过事件总线解耦，保证了系统的高内聚和数据一致性。

核心服务

XAPI 目前已上线四大服务：动态卡片服务、网站统计服务、二维码生成服务 和 文件存储服务。

1. X-CARD 动态卡片服务

X-CARD 是一个轻量级、动态化的内容下发系统，非常适合用于应用内的 公告、通知、运营活动卡片、Dashboard 信息模块 等场景，当前网站主页右侧卡片即由 X-CARD 提供支持。

核心能力:
- 动态创建：通过 API 随时创建包含标题、内容、图片和跳转链接的卡片。
- 优先级排序：设置卡片优先级，智能控制前端展示顺序。
- 自动过期：为卡片设置有效期，到期后自动下线，无需手动管理。
- 展示控制：可限制每张卡片的最大展示次数，实现精准投放。

2. X-STATS 网站统计服务

X-STATS 是一个简单、无 Cookie 的网站访问统计服务，用于轻量级地追踪页面或链接的访问数据，对访客隐私友好，当前页面下方的数据统计即由 X-STATS 提供支持。

核心能力:
- 访问追踪：一行代码即可追踪任何 URL 的访问次数 (PV)。
- 来源分析：自动解析并统计访问来源域名 (Referer)。
- 数据看板：提供热门 URL 和热门来源排行榜，快速了解流量分布。
- 数据概览：提供用户维度的总访问量、总来源数等聚合数据。

3. X-QRCODE 二维码生成服务

X-QRCODE 是一个快速、可靠的二维码生成服务，让您可以动态生成各种二维码，非常适合用于 产品链接分享、活动推广、移动端快速访问 等场景。

核心能力:
- 即时生成：通过 API 实时生成任意 URL 的二维码，支持自定义尺寸（128-1024px）。
- 自动管理：二维码可设置有效期（最长10年），到期自动清理，避免存储浪费。
- 批量管理：支持查询和管理账户下所有二维码，方便统一维护。
- Base64 输出：生成的二维码以 Base64 格式返回，可直接嵌入网页或移动应用。
- 高性能缓存：基于 Redis 存储，确保毫秒级生成和获取速度。

4. X-FILE 文件存储服务

X-FILE 是一个安全、多租户的文件存储服务，专为开发者设计，用于处理 临时文件分享、用户内容上传（如头像、附件）、数据报告分发 等场景。

核心能力:
- 安全的多租户隔离：每个用户的文件都存储在独立目录中，数据完全隔离。
- 灵活的配额管理：提供从 GB 到 TB 级别的多级存储配额，并实时追踪使用情况。
- 临时链接与安全控制：可为文件设置自定义过期时间（如 "1h", "7d"）和最大下载次数。
- 大文件支持：支持高达 256MB（可配置）的单文件上传，满足多数业务需求。
- 完整的 API 管理：提供上传、下载、列表查询、删除和配额查询等全套管理接口。

API 快速上手

注册成功后，您会获得两种密钥：

私有密钥 (sk-...): 用于执行创建、修改、删除等需要安全认证的操作。
公共密钥 (pk-...): 用于执行数据追踪、公开数据查询等可以暴露在前端的操作。

示例 1: 创建一张公告卡片 (使用私有密钥)

使用您的 sk- 密钥创建一个有效期为 7 天的公告卡片。

export XAPI_KEY="你的XAPI-KEY" # sk- 开头的密钥

curl -X POST https://api.xabcstack.com/x-card \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAPI_KEY" \
  -d '{
      "title": "🎉 新功能上线！",
      "content": "我们的 网站统计服务现已全面开放，快来体验吧！",
      "link": "https://xabcstack.com",
      "priority": 10,
      "days": 7
    }'

示例 2: 在前端获取并展示卡片 (使用公共密钥)

在您的网站或 App 中，使用 pk- 公钥获取所有有效的卡片并展示。

export XAPI_PUBLIC_KEY="你的-公共-密钥" # pk- 开头的公钥

curl -X GET "https://api.xabcstack.com/x-card/${XAPI_PUBLIC_KEY}"

示例 3: 在前端追踪一次页面访问 (使用公共密钥)

将此请求嵌入在您的网站前端代码中，即可追踪页面访问。

export XAPI_PUBLIC_KEY="你的-公共-密钥" # pk- 开头的公钥

curl -X POST "https://api.xabcstack.com/x-urls/${XAPI_PUBLIC_KEY}/track" \
  -H "Content-Type: application/json" \
  -H "Referer: https://www.google.com/" \
  -d '{
      "url": "https://yoursite.com/pricing"
    }'

示例 4: 获取统计数据概览 (使用公共密钥)

获取您的账户下所有 URL 的统计概览，包括总访问量、热门 URL Top 10 等。

export XAPI_PUBLIC_KEY="你的-公共-密钥" # pk- 开头的公钥

curl -X GET "https://api.xabcstack.com/x-urls/${XAPI_PUBLIC_KEY}/overview?limit=10"

示例 5: 生成一个二维码 (使用私有密钥)

为您的网站生成一个二维码，有效期 30 天，尺寸 512px。

export XAPI_KEY="你的XAPI-KEY" # sk- 开头的密钥

curl -X POST https://api.xabcstack.com/x-qrcode \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAPI_KEY" \
  -d '{
      "url": "https://yoursite.com/promotion",
      "title": "夏季促销活动",
      "size": 512,
      "days": 30
    }'

示例 6: 获取指定二维码 (使用私有密钥)

根据二维码 ID 获取详细信息。

export XAPI_KEY="你的XAPI-KEY" # sk- 开头的密钥
export QR_CODE_ID="qr_123_1234567890" # 从创建接口返回的 ID

curl -X GET "https://api.xabcstack.com/x-qrcode/${QR_CODE_ID}" \
  -H "Authorization: Bearer $XAPI_KEY"

示例 7: 列出所有二维码 (使用私有密钥)

获取您账户下的所有有效二维码列表。

export XAPI_KEY="你的XAPI-KEY" # sk- 开头的密钥

curl -X GET https://api.xabcstack.com/x-qrcode \
  -H "Authorization: Bearer $XAPI_KEY"

示例 8: 删除二维码 (使用私有密钥)

删除指定的二维码。

export XAPI_KEY="你的XAPI-KEY" # sk- 开头的密钥
export QR_CODE_ID="qr_123_1234567890" # 要删除的二维码 ID

curl -X DELETE "https://api.xabcstack.com/x-qrcode/${QR_CODE_ID}" \
  -H "Authorization: Bearer $XAPI_KEY"

示例 9: 上传一个临时文件 (使用私有密钥)

上传一个 report.pdf 文件，设置 7 天后过期，最多下载 10 次。

export XAPI_KEY="你的XAPI-KEY" # sk- 开头的密钥

curl -X POST https://api.xabcstack.com/x-file/upload \
  -H "Authorization: Bearer $XAPI_KEY" \
  -F "[email protected]" \
  -F "expiration=7d" \
  -F "download_limit=10"

示例 10: 查询您的文件存储配额 (使用私有密钥)

获取当前账户的存储空间使用情况。

export XAPI_KEY="你的XAPI-KEY" # sk- 开头的密钥

curl -X GET https://api.xabcstack.com/x-file/quota \
  -H "Authorization: Bearer $XAPI_KEY"

示例 11: 列出您已上传的文件 (使用私有密钥)

获取您账户下所有文件的列表，支持分页。

export XAPI_KEY="你的XAPI-KEY" # sk- 开头的密钥

curl -X GET "https://api.xabcstack.com/x-file/list?page=1&page_size=10" \
  -H "Authorization: Bearer $XAPI_KEY"

示例 12: 删除一个文件 (使用私有密钥)

根据上传后返回的 token 删除文件。

export XAPI_KEY="你的XAPI-KEY" # sk- 开头的密钥
export FILE_TOKEN="abc123..." # 从上传接口返回的 token

curl -X DELETE "https://api.xabcstack.com/x-file/delete?token=${FILE_TOKEN}" \
  -H "Authorization: Bearer $XAPI_KEY"

使用场景示例

场景 1: 营销活动二维码

为线下活动创建带有效期的二维码，活动结束后自动失效：

// 创建活动二维码，7天后自动失效
const response = await fetch('https://api.xabcstack.com/x-qrcode', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${XAPI_KEY}`
  },
  body: JSON.stringify({
    url: 'https://yoursite.com/black-friday-2025',
    title: '黑色星期五限时优惠',
    size: 512,
    days: 7
  })
});

const data = await response.json();
// 直接在页面中使用 Base64 图片
document.getElementById('qr-code').src = data.qrcode.image_data;

场景 2: 产品说明书二维码

为产品创建长期有效的二维码，打印在包装上：

import requests
import json

# 创建产品说明书二维码，10年有效期
response = requests.post(
    'https://api.xabcstack.com/x-qrcode',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {XAPI_KEY}'
    },
    data=json.dumps({
        'url': 'https://docs.yoursite.com/product/model-x',
        'title': 'Model X 使用说明书',
        'size': 256,
        'days': 3650  # 10年
    })
)

qr_data = response.json()
print(f"二维码 ID: {qr_data['qrcode']['id']}")
# 保存 Base64 图片用于打印

场景 3: 动态内容分发

结合 X-CARD 和 X-QRCODE 服务，创建可扫码查看的动态内容：

// 先创建一个活动卡片
const cardResponse = await fetch('https://api.xabcstack.com/x-card', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${XAPI_KEY}`
  },
  body: JSON.stringify({
    title: '🎁 新年特惠活动',
    content: '全场商品8折优惠，仅限本周！',
    link: 'https://yoursite.com/new-year-sale',
    priority: 100,
    days: 7
  })
});

// 为卡片链接生成二维码
const qrResponse = await fetch('https://api.xabcstack.com/x-qrcode', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${XAPI_KEY}`
  },
  body: JSON.stringify({
    url: 'https://yoursite.com/new-year-sale',
    title: '新年特惠活动二维码',
    size: 512,
    days: 7
  })
});

// 现在用户可以扫码直接访问活动页面

场景 4: 生成并分享临时数据报告

在后端服务中生成一份数据报告，上传到 X-FILE 并获得一个有时效性的分享链接。

import requests

# 1. 在本地生成一份报告文件
with open("monthly_report.csv", "w") as f:
    f.write("Date,Users,Revenue\n")
    f.write("2024-01-01,1500,3000\n")

# 2. 上传文件到 X-FILE，设置24小时后过期，只能下载5次
XAPI_KEY = "你的XAPI-KEY" # sk- 开头的密钥
file_path = "monthly_report.csv"

with open(file_path, 'rb') as f:
    response = requests.post(
        'https://api.xabcstack.com/x-file/upload',
        headers={'Authorization': f'Bearer {XAPI_KEY}'},
        files={'file': (file_path, f, 'text/csv')},
        data={
            'expiration': '24h',
            'download_limit': '5'
        }
    )

# 3. 获取分享链接
if response.status_code == 200:
    result = response.json()
    print(f"报告上传成功！")
    print(f"分享链接: {result['direct_link']}")
    print(f"链接将在 {result['expires_in']} 后失效")
else:
    print(f"上传失败: {response.text}")

# 现在可以将这个链接通过邮件或消息发送给相关人员