Uploading Media

Before attaching new photos or videos to posts, messages, or vault albums, you must upload the files to Fansly. Because media files can be large, the API processes uploads asynchronously.

This guide walks you through the 2-step media upload process using the Upload Media endpoints.

The Workflow Overview

To upload files, you will follow these general steps:

Step 1: Initiate the Upload

Upload your target file by making a POST request to the initiate endpoint:

POST /api/fansly/{accountId}/media/upload

This request must be sent as multipart/form-data containing the file parameter.

Implementation Examples

curl -X POST "https://v1.apifansly.com/api/fansly/{accountId}/media/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch("https://v1.apifansly.com/api/fansly/{accountId}/media/upload", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY"
  },
  body: formData
});

const data = await response.json();
console.log("Job ID:", data.data.jobId);

import requests

url = "https://v1.apifansly.com/api/fansly/{accountId}/media/upload"
headers = {"x-api-key": "YOUR_API_KEY"}
files = {"file": open("image.jpg", "rb")}

response = requests.post(url, headers=headers, files=files)
data = response.json()
print("Job ID:", data["data"]["jobId"])

The endpoint will return a 201 Created status indicating that the upload job has been queued:

{
  "statusCode": 201,
  "message": "Success",
  "data": {
    "success": true,
    "jobId": "8",
    "bucketName": "87550882346...",
    "message": "Upload job queued. Use the status endpoint to track progress."
  }
}

Step 2: Track Upload Status

Poll the status endpoint periodically (e.g., every 2–5 seconds) to track the background compression and processing tasks:

GET /api/fansly/media/upload/{jobId}/status

Checking the State

In the response body, track the value of data.state:

• waiting / active: The file is still uploading or being processed by the backend. Continue polling.
• completed: The file has been successfully uploaded and processed. You can now use the media.
• failed: The upload or compression failed. Check the logs for details.

Success Response Example

Once state reaches completed, you will find the mediaId in the response:

{
  "statusCode": 200,
  "message": "Success",
  "data": {
    "success": true,
    "jobId": "8",
    "state": "completed",
    "progress": 100,
    "result": {
      "success": true,
      "mediaId": "12345678912345678"
    }
  }
}

Step 3: Attach the Media

Once you have the mediaId (e.g., 12345678912345678), you can pass it inside the mediaIds array to create new posts or send direct messages:

• Posts: Pass to Create Post.
• Messages: Pass to Send Message.