Fanvue API Poster

A simple Docker-based tool to create posts on Fanvue from your Ubuntu machine.

Quick Start

1. Get Your Access Token

Run the helper script to get your OAuth access token:

python3 get_token.py

Follow the prompts to authorize the app and get your access token.

2. Configure Your Post

Copy the example config and edit it:

cp config.example.json config.json

Edit config.json:

{
  "api": {
    "access_token": "YOUR_ACCESS_TOKEN_HERE"
  },
  "post": {
    "audience": "subscribers",
    "text_file": "/path/to/your/caption.txt"
  },
  "media": {
    "folder": "/path/to/your/images"
  }
}

3. Create Your Caption

Write your post caption in a text file (supports emojis and multi-line):

echo "Check out my new post!" > caption.txt

4. Create a Post

make post

That's it! The script will:

• Load your caption from the text file
• Auto-discover all images/videos in your media folder
• Upload all media files to Fanvue (using multipart upload)
• Create the post with all media attached

Configuration Options

API Settings

• base_url - Fanvue API base URL (default: https://api.fanvue.com)
• version - API version (default: 2025-06-26)
• access_token - Your OAuth access token (required)

Post Settings

• audience (required) - Who can see the post:

  • "subscribers" - Only subscribers
  • "followers-and-subscribers" - Everyone who follows you

• text_file (optional) - Path to text file containing post caption

  • Supports multi-line text and emojis
  • Alternative: use text field for inline text

• text (optional) - Post caption/text content (inline)

  • Use this OR text_file, not both

• price (optional) - Price in dollars if you want to charge for this content

  • Example: 9.99 for $9.99
  • Set to null for free content

• publishAt (optional) - Schedule the post for later

  • Format: ISO 8601 datetime
  • Example: "2025-10-26T15:00:00Z"
  • Set to null to publish immediately

• expiresAt (optional) - When the post should expire

  • Format: ISO 8601 datetime
  • Example: "2025-12-31T23:59:59Z"
  • Set to null for no expiration

Preview Post Settings

The post_preview section is used with make preview to create preview posts (e.g., for followers before posting subscriber content):

• audience - Set to "followers-and-subscribers" to reach everyone
• text_file - Path to preview caption text file (e.g., preview.txt)
• preview_image - Path to a single preview image
• price, publishAt, expiresAt - Same as regular post settings

Media Settings

• folder - Path to folder containing media files

  • If files array is empty, all images/videos in the folder will be auto-discovered
  • Supported formats: .jpg, .jpeg, .png, .gif, .mp4, .mov, .webp

• files (optional) - Array of specific filenames to attach

  • Leave empty ([]) to auto-discover all media files in the folder

• uuids (optional) - Array of pre-uploaded media UUIDs (if you uploaded separately)

Available Commands

make help       # Show all available commands
make post       # Create a post on Fanvue (main command)
make preview    # Create a preview post (single image for followers)
make build      # Build Docker image only
make logs       # View logs from last run
make validate   # Check if config.json is valid
make clean      # Clean up logs and containers
make shell      # Open shell in container for debugging

Examples

Post with Images and Text File

{
  "api": {
    "access_token": "your_token_here"
  },
  "post": {
    "audience": "subscribers",
    "text_file": "/home/user/captions/my_post.txt"
  },
  "media": {
    "folder": "/home/user/photos/set1"
  }
}

The script will automatically find all images in /home/user/photos/set1, upload them, and attach them to the post.

Simple Text Post (Inline)

{
  "post": {
    "audience": "subscribers",
    "text": "Hello everyone! 👋"
  }
}

Post with Specific Images

{
  "post": {
    "audience": "followers-and-subscribers",
    "text": "Check out this photo!"
  },
  "media": {
    "folder": "/home/user/photos",
    "files": ["sunset.jpg", "beach.png"]
  }
}

Paid Content

{
  "post": {
    "audience": "subscribers",
    "text_file": "/home/user/captions/exclusive.txt",
    "price": 4.99
  },
  "media": {
    "folder": "/home/user/photos/exclusive"
  }
}

Scheduled Post

{
  "post": {
    "audience": "subscribers",
    "text": "This will post tomorrow at 3pm",
    "publishAt": "2025-10-26T15:00:00Z"
  }
}

Troubleshooting

"config.json not found"

Copy config.example.json to config.json and update it with your settings.

"Please set your access token"

Run python3 get_token.py to get a new access token, then update config.json.

"Failed to create post: 401"

Your access token is invalid or expired. Get a new token.

"Failed to create post: 403" or "Insufficient scopes"

Your token doesn't have the required scopes. You need both write:post and write:media scopes. Enable them in the Fanvue Developer Portal and get a new token with python3 get_token.py.

Check Logs

make logs

Project Structure

fanvue-api/
├── fanvue_poster.py      # Main Python script
├── config.json           # Your configuration (gitignored)
├── config.example.json   # Configuration template
├── docker-compose.yml    # Docker Compose configuration
├── Dockerfile            # Docker image definition
├── Makefile             # Convenient commands
├── requirements.txt      # Python dependencies
├── .gitignore           # Git ignore rules
├── README.md            # This file
├── media/               # Your images/videos (gitignored)
└── logs/                # Application logs (gitignored)

Notes

• Media Upload: Full multipart upload is implemented! Files are uploaded in 10MB chunks for reliability. Large files are handled automatically.
• OAuth Scopes: You need both write:post and write:media scopes enabled in the Fanvue Developer Portal.
• Token Expiry: Access tokens expire after 1 hour. If you get 401 errors, get a new token with python3 get_token.py.
• Auto Image Count: The script automatically replaces image count patterns in your caption. If your text file contains (1 image) or (20 images), it will be updated to match the actual number of uploaded images.
• Security: Never commit config.json with your access token to git. It's in .gitignore by default.

Getting an Access Token

Fanvue uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for security. We've included a helper script to make this easy:

Easy Method (Recommended)

1. Create your app in Fanvue Developer Portal
2. Enable scopes: Check both write:post and write:media in the portal
3. Set redirect URI to: http://localhost:8080/callback
4. Run the helper script:

   python3 get_token.py

5. Follow the interactive prompts:
   • Enter your Client ID
   • Open the generated URL in your browser
   • Approve the app
   • Copy the code from the redirect URL
   • Paste it back into the script
   • Enter your Client Secret
   • Run the generated curl command
6. Copy the access_token to your config.json

Important: The helper script requests both write:post and write:media scopes automatically.

Manual Method (Advanced)

If you prefer to do it manually, you need to generate PKCE parameters:

1. Generate a random code_verifier (43-128 characters)
2. Create code_challenge as base64url(SHA256(code_verifier))
3. Build authorization URL:

   https://auth.fanvue.com/oauth2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8080/callback&response_type=code&scope=write:post%20write:media&state=random123456&code_challenge=YOUR_CODE_CHALLENGE&code_challenge_method=S256
   

4. After authorization, exchange the code for a token:

   curl -X POST https://auth.fanvue.com/oauth2/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=YOUR_CODE" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "redirect_uri=http://localhost:8080/callback" \
     -d "code_verifier=YOUR_CODE_VERIFIER"

The helper script (get_token.py) handles all the PKCE complexity for you!

License

MIT