fanvue

Fanvue API Skill

Integrate with the Fanvue creator platform to manage chats, posts, subscribers, earnings insights, and media content.

Prerequisites

1. Create an OAuth Application

1. Go to the Fanvue Developer Portal
2. Create a new OAuth application
3. Note your Client ID and Client Secret
4. Configure your Redirect URI (e.g., https://your-app.com/callback)

2. Environment Variables

Set these environment variables:

FANVUE_CLIENT_ID=your_client_id
FANVUE_CLIENT_SECRET=your_client_secret
FANVUE_REDIRECT_URI=https://your-app.com/callback

---

Authentication

Fanvue uses OAuth 2.0 with PKCE (Proof Key for Code Exchange). All API requests require:

• Authorization Header: Bearer <access_token>
• API Version Header: X-Fanvue-API-Version: 2025-06-26

OAuth Scopes

Request these scopes based on your needs:

Scope	Access
openid	OpenID Connect authentication
offline_access	Refresh token support
offline	Offline access
read:self	Read authenticated user profile
read:chat	Read chat conversations
write:chat	Send messages, update chats
read:post	Read posts
write:post	Create posts
read:creator	Read subscriber/follower data
read:media	Read media vault
write:tracking_links	Manage campaign links
read:insights	Read earnings/analytics (creator accounts)
read:subscribers	Read subscriber lists (creator accounts)

Note: Some endpoints (subscribers, insights, earnings) require a creator account and may need additional scopes not listed in the public documentation.

Quick Auth Flow

import { randomBytes, createHash } from 'crypto';

// 1. Generate PKCE parameters
const codeVerifier = randomBytes(32).toString('base64url');
const codeChallenge = createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');

// 2. Build authorization 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');

// Redirect user to: authUrl.toString()

// 3. Exchange authorization code for tokens
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 Base URL

All API requests go to: https://api.fanvue.com

Standard Request Headers

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

---

Agent Automation

These workflows are designed for AI agents automating Fanvue creator accounts.

Accessing Images (with Signed URLs)

The basic /media endpoint only returns metadata. To get actual viewable URLs, use the variants query parameter:

// Step 1: List all media
const list = await fetch('https://api.fanvue.com/media', { headers });
const { data } = await list.json();

// Step 2: Get signed URLs for a specific media item
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: '...' }
// ]

Variant Types:

• main - Full resolution original
• thumbnail - Optimized preview (smaller)
• blurred - Censored version for teasers

Creating a Post with Media

// Step 1: Have existing media UUIDs from vault
const mediaIds = ['media-uuid-1', 'media-uuid-2'];

// Step 2: Create post
const response = await fetch('https://api.fanvue.com/posts', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    text: 'Check out my new content! 🔥',
    mediaIds,
    audience: 'subscribers',  // or 'followers-and-subscribers'
    // Optional:
    price: null,              // Set for pay-per-view
    publishAt: null,          // Set for scheduled posts
  }),
});

Audience Options:

Value	Who Can See
subscribers	Paid subscribers only
followers-and-subscribers	Both free followers and subscribers

Sending Messages with Media

// Get subscriber list for decision making
const subs = await fetch('https://api.fanvue.com/creators/list-subscribers', { headers });
const { data: subscribers } = await subs.json();

// Get top spenders for VIP targeting
const vips = await fetch('https://api.fanvue.com/insights/get-top-spenders', { headers });
const { data: topSpenders } = await vips.json();

// Send personalized message with media
await fetch('https://api.fanvue.com/chat-messages', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    recipientUuid: subscribers[0].userUuid,
    content: 'Thanks for being a subscriber! Here\'s something special for you 💕',
    mediaIds: ['vault-media-uuid'],  // Attach media from vault
  }),
});

// Or send to multiple subscribers at once
await fetch('https://api.fanvue.com/chat-messages/mass', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    recipientUuids: subscribers.map(s => s.userUuid),
    content: 'New exclusive content just dropped! 🎉',
    mediaIds: ['vault-media-uuid'],
  }),
});

Agent Decision Context

For effective automation, gather this context:

interface AutomationContext {
  // Current media in vault
  media: {
    uuid: string;
    name: string;
    type: 'image' | 'video';
    description: string;  // AI-generated caption
    signedUrl: string;    // From variants query
  }[];
  
  // Audience data
  subscribers: {
    uuid: string;
    name: string;
    subscribedAt: string;
    tier: string;
  }[];
  
  // Engagement signals
  topSpenders: {
    uuid: string;
    totalSpent: number;
  }[];
  
  // Recent earnings for trend analysis
  earnings: {
    period: string;
    total: number;
    breakdown: { type: string; amount: number }[];
  };
}

---

Core Operations

Get Current User

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

List Chats

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

Send a Message

const response = await fetch('https://api.fanvue.com/chat-messages', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    recipientUuid: 'user-uuid-here',
    content: 'Hello! Thanks for subscribing!',
  }),
});

Create a Post

const response = await fetch('https://api.fanvue.com/posts', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    content: 'New content available!',
    // Add media IDs, pricing, etc.
  }),
});

Get Earnings

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

List Subscribers

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

---

API Reference

See api-reference.md for the complete endpoint documentation.

---

Token Refresh

Access tokens expire. Use the refresh token to get new ones:

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();

---

Error Handling

Common HTTP status codes:

Status	Meaning
200	Success
400	Bad request - check your parameters
401	Unauthorized - token expired or invalid
403	Forbidden - missing required scope
404	Resource not found
429	Rate limited - slow down requests

---

Resources

• Fanvue API Documentation
• OAuth 2.0 Guide
• Developer Portal
• Fanvue App Starter Kit