# OnlyFans Python SDK

> A typed, production-ready Python client for the OnlyFans API. Authenticate once, call any endpoint, and ship reliable creator tools with less boilerplate.

- Requires Python 3.9+
- Sync (`OnlyFansAPI`) and async (`AsyncOnlyFansAPI`) clients
- Source: https://github.com/onlyfansapi/onlyfansapi-python
- Package: `onlyfans` on PyPI

## Install

```bash
pip install onlyfans
```

## Quick start

```python
from onlyfansapi import OnlyFansAPI

client = OnlyFansAPI()  # reads ONLYFANSAPI_API_KEY

chats = client.chats.list(
    "acct_XXXXXXXXXXXXX",
    filter="unread",
    limit="20",
)

for chat in chats.data:
    unread = chat.unread_messages_count
    print(f"@{chat.fan.username} ({unread} unread): {chat.last_message.text}")
```

Send a message with media:

```python
from onlyfansapi import OnlyFansAPI

client = OnlyFansAPI()

sent = client.chats.messages.send(
    "chat_id",
    account="acct_XXXXXXXXXXXXX",
    text="Hey! Here is something new for you",
    media_files=["ofapi_media_XXXXXXXXXXXXX"],
    price=10,
)

print(f"Message sent #{sent.data.id}")
```

Other examples on the page: link stats, link spenders, chat messages with pagination (`messages.api_pagination.next_page`), and streaming media downloads via `client.media.with_streaming_response.download(...)`.

## Features

- **Sync and async** — Use `OnlyFansAPI` for synchronous work or `AsyncOnlyFansAPI` with `await`.
- **Typed models** — TypedDict requests and Pydantic responses bring autocomplete to every call.
- **Flexible uploads** — Upload bytes, PathLike values, or filename and media-type tuples.

From a quick script to a high-concurrency service, the client scales with you.

## Built for real products

Use one consistent client across dashboards, internal operations, and automated workflows: analytics dashboards, media workflows, internal automation, multi-account tools, reporting pipelines, and custom integrations.

## FAQ

### How do I authenticate?

Set the `ONLYFANSAPI_API_KEY` environment variable or pass `api_key` when creating the client. Environment-based configuration keeps credentials out of source control.

### Does the SDK include request and response types?

Yes. Request parameters are TypedDicts and responses are Pydantic models, giving you autocomplete and docs in your editor. Python 3.9+.

### What happens when a request fails?

A subclass of `onlyfansapi.APIError` is raised — `APIConnectionError`, `RateLimitError`, `APIStatusError` with `status_code` and `response`. Connection errors, timeouts, 429s, and 5xx responses are retried twice automatically with exponential backoff.

### Can I upload files?

Yes. Pass bytes, a PathLike instance, or a `(filename, contents, media type)` tuple. The async client reads files asynchronously.

### Can I call an endpoint that is not documented yet?

Yes. Use the client's custom-request support to hit undocumented endpoints and parameters while keeping authentication and retries.

## Links

- Get your API key: https://app.onlyfansapi.com/register
- Source on GitHub: https://github.com/onlyfansapi/onlyfansapi-python
- API reference: https://docs.onlyfansapi.com/api-reference/overview
- All SDKs: https://onlyfansapi.com/sdk