name: Fanvue
description: 通过 OAuth 2.0 API 管理 Fanvue 创作者平台上的内容、聊天、订阅者和收益。

Fanvue API 技能

与 Fanvue 创作者平台集成，以管理聊天、帖子、订阅者、收益洞察和媒体内容。

前提条件

1. 创建 OAuth 应用

1. 访问 Fanvue 开发者门户
2. 创建一个新的 OAuth 应用
3. 记录你的 Client ID 和 Client Secret
4. 配置你的 Redirect URI（例如：https://your-app.com/callback）

2. 环境变量

设置以下环境变量：

FANVUE_CLIENT_ID=你的客户端ID
FANVUE_CLIENT_SECRET=你的客户端密钥
FANVUE_REDIRECT_URI=https://your-app.com/callback

认证

Fanvue 使用 OAuth 2.0 with PKCE（Proof Key for Code Exchange）。所有 API 请求都需要：

• Authorization 请求头: Bearer <access_token>
• API 版本请求头: X-Fanvue-API-Version: 2025-06-26

OAuth 权限范围

根据你的需求请求以下权限范围：

注意：某些端点（如订阅者、洞察、收益）需要 创作者账户，并且可能需要公共文档中未列出的额外权限范围。

快速认证流程

import { randomBytes, createHash } from 'crypto';

// 1. 生成 PKCE 参数
const codeVerifier = randomBytes(32).toString('base64url');
const codeChallenge = createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');

// 2. 构建授权 URL
const authUrl = new URL('https://auth.fanvue.com/oauth2/auth');
authUrl.searchParams.set('client_id', process.env.FANVUE_CLIENT_ID);
authUrl.searchParams.set('redirect_uri', process.env.FANVUE_REDIRECT_URI);
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'openid offline_access read:self read:chat write:chat read:post');
authUrl.searchParams.set('state', randomBytes(32).toString('hex'));
authUrl.searchParams.set('code_challenge', codeChallenge);
authUrl.searchParams.set('code_challenge_method', 'S256');

// 将用户重定向到：authUrl.toString()

// 3. 使用授权码交换令牌
const tokenResponse = await fetch('https://auth.fanvue.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: process.env.FANVUE_CLIENT_ID,
    client_secret: process.env.FANVUE_CLIENT_SECRET,
    code: authorizationCode,
    redirect_uri: process.env.FANVUE_REDIRECT_URI,
    code_verifier: codeVerifier,
  }),
});

const tokens = await tokenResponse.json();
// tokens.access_token, tokens.refresh_token

API 基础 URL

所有 API 请求发送至：https://api.fanvue.com

标准请求头

const headers = {
  'Authorization': `Bearer ${accessToken}`,
  'X-Fanvue-API-Version': '2025-06-26',
  'Content-Type': 'application/json',
};

智能体自动化

以下工作流专为自动化 Fanvue 创作者账户的 AI 智能体设计。

访问图片（使用签名 URL）

基础的 /media 端点仅返回元数据。要获取实际可查看的 URL，请使用 variants 查询参数：

// 步骤 1：列出所有媒体
const list = await fetch('https://api.fanvue.com/media', { headers });
const { data } = await list.json();

// 步骤 2：获取特定媒体项的签名 URL
const media = await fetch(
  `https://api.fanvue.com/media/${uuid}?variants=main,thumbnail,blurred`, 
  { headers }
);
const { variants } = await media.json();

// variants = [
//   { variantType: 'main', url: 'https://media.fanvue.com/private/...' },
//   { variantType: 'thumbnail', url: '...' },
//   { variantType: 'blurred', url: '...' }
// ]

变体类型：
- main - 原始全分辨率
- thumbnail - 优化预览（较小）
- blurred - 用于预览的模糊版本

创建包含媒体的帖子

// 步骤 1：从媒体库获取已有的媒体 UUID
const mediaIds = ['media-uuid-1', 'media-uuid-2'];

// 步骤 2：创建帖子
const response = await fetch('https://api.fanvue.com/posts', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    text: '看看我的新内容！ 🔥',
    mediaIds,
    audience: 'subscribers',  // 或 'followers-and-subscribers'
    // 可选：
    price: null,              // 设置为付费查看
    publishAt: null,          // 设置为定时发布
  }),
});

受众选项：
| 值 | 谁可以看见 |
| :--- | :--- |
| subscribers | 仅付费订阅者 |
| followers-and-subscribers | 免费关注者和订阅者均可 |

发送包含媒体的消息

// 获取订阅者列表用于决策
const subs = await fetch('https://api.fanvue.com/creators/list-subscribers', { headers });
const { data: subscribers } = await subs.json();

// 获取高消费用户用于 VIP 定向
const vips = await fetch('https://api.fanvue.com/insights/get-top-spenders', { headers });
const { data: topSpenders } = await vips.json();

// 发送个性化消息并附带媒体
await fetch('https://api.fanvue.com/chat-messages', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    recipientUuid: subscribers[0].userUuid,
    content: '感谢订阅！这是为你准备的特别内容 💕',
    mediaIds: ['vault-media-uuid'],  // 附加媒体库中的媒体
  }),
});

// 或一次性发送给多个订阅者
await fetch('https://api.fanvue.com/chat-messages/mass', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    recipientUuids: subscribers.map(s => s.userUuid),
    content: '新的独家内容刚刚发布！ 🎉',
    mediaIds: ['vault-media-uuid'],
  }),
});

智能体决策上下文

为实现有效自动化，请收集以下上下文信息：

interface AutomationContext {
  // 媒体库中的当前媒体
  media: {
    uuid: string;
    name: string;
    type: 'image' | 'video';
    description: string;  // AI 生成的描述
    signedUrl: string;    // 来自 variants 查询
  }[];

  // 受众数据
  subscribers: {
    uuid: string;
    name: string;
    subscribedAt: string;
    tier: string;
  }[];

  // 互动信号
  topSpenders: {
    uuid: string;
    totalSpent: number;
  }[];

  // 近期收益用于趋势分析
  earnings: {
    period: string;
    total: number;
    breakdown: { type: string; amount: number }[];
  };
}

核心操作

获取当前用户

const response = await fetch('https://api.fanvue.com/users/me', { headers });
const user = await response.json();

列出聊天

const response = await fetch('https://api.fanvue.com/chats', { headers });
const { data, pagination } = await response.json();

发送消息

const response = await fetch('https://api.fanvue.com/chat-messages', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    recipientUuid: 'user-uuid-here',
    content: '你好！感谢订阅！',
  }),
});

创建帖子

const response = await fetch('https://api.fanvue.com/posts', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    content: '新内容已上线！',
    // 可添加媒体 ID、定价等
  }),
});

获取收益

const response = await fetch('https://api.fanvue.com/insights/get-earnings', { headers });
const earnings = await response.json();

列出订阅者

const response = await fetch('https://api.fanvue.com/creators/list-subscribers', { headers });
const { data } = await response.json();

API 参考

完整端点文档请参阅 api-reference.md。

令牌刷新

访问令牌会过期。使用刷新令牌获取新的令牌：

const response = await fetch('https://auth.fanvue.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    client_id: process.env.FANVUE_CLIENT_ID,
    client_secret: process.env.FANVUE_CLIENT_SECRET,
    refresh_token: currentRefreshToken,
  }),
});

const newTokens = await response.json();

错误处理

常见的 HTTP 状态码：

资源

• Fanvue API 文档
• OAuth 2.0 指南
• 开发者门户
• Fanvue 应用入门套件