post-upload 1.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- post_upload-1.2.0/CHANGELOG.md +37 -0
- post_upload-1.2.0/LICENSE +21 -0
- post_upload-1.2.0/MANIFEST.in +3 -0
- post_upload-1.2.0/PKG-INFO +548 -0
- post_upload-1.2.0/README.md +503 -0
- post_upload-1.2.0/indreelforge/__init__.py +30 -0
- post_upload-1.2.0/post_upload/__init__.py +70 -0
- post_upload-1.2.0/post_upload/_version.py +3 -0
- post_upload-1.2.0/post_upload/client.py +1147 -0
- post_upload-1.2.0/post_upload/py.typed +0 -0
- post_upload-1.2.0/post_upload/types.py +63 -0
- post_upload-1.2.0/post_upload.egg-info/PKG-INFO +548 -0
- post_upload-1.2.0/post_upload.egg-info/SOURCES.txt +19 -0
- post_upload-1.2.0/post_upload.egg-info/dependency_links.txt +1 -0
- post_upload-1.2.0/post_upload.egg-info/requires.txt +4 -0
- post_upload-1.2.0/post_upload.egg-info/top_level.txt +2 -0
- post_upload-1.2.0/pyproject.toml +3 -0
- post_upload-1.2.0/setup.cfg +4 -0
- post_upload-1.2.0/setup.py +63 -0
- post_upload-1.2.0/tests/test_chunked.py +358 -0
- post_upload-1.2.0/tests/test_client.py +522 -0
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.2.0 (2026-11-22)
|
|
4
|
+
|
|
5
|
+
### Renamed: `indreelforge` is now `post-upload`
|
|
6
|
+
|
|
7
|
+
- The distribution is now **`post-upload`** on PyPI (`pip install post-upload`) and the import package is **`post_upload`**. The main names are `PostUpload` and `PostUploadError`.
|
|
8
|
+
- Backward compatible: `IndReelForge`, `InReelForge`, `IndReelForgeError` and `InReelForgeError` are aliases of the new names, and the package still ships an `indreelforge` module (`import indreelforge`, `from indreelforge.client import ...`) that re-exports `post_upload` and emits a `DeprecationWarning`.
|
|
9
|
+
- Default API address is now `https://api.post-upload.com` (the old address keeps working while the move completes).
|
|
10
|
+
- `api_key` is optional: when omitted it is read from `POST_UPLOAD_API_KEY`, then `INDREELFORGE_API_KEY`.
|
|
11
|
+
- `User-Agent` is now `post-upload-python/<version>`.
|
|
12
|
+
- The old `indreelforge` PyPI package gets no further releases.
|
|
13
|
+
|
|
14
|
+
### Large videos: chunked upload up to 500 MB
|
|
15
|
+
|
|
16
|
+
- `upload_video` sends local files larger than 95 MiB (`CHUNKED_THRESHOLD`, or the `chunked_threshold` client option) through the chunked upload endpoints automatically, then posts them by `staged_file_id`. `chunked=True` / `chunked=False` force or disable it.
|
|
17
|
+
- Parts are sent sequentially, exactly the server's `chunk_size` each, read from disk part by part, and retried with exponential backoff on 429, 5xx and network errors (honouring `Retry-After`; `max_retries` client option, default 5). A failed upload cancels its session.
|
|
18
|
+
- `on_progress(sent_bytes, total_bytes)` callback.
|
|
19
|
+
- New methods: `upload_large_file()` (returns the `staged_file_id`), `create_upload_session()`, `upload_part()`, `complete_upload_session()`, `get_upload_session()`, `abort_upload_session()`.
|
|
20
|
+
- `upload_video` also accepts `video_file` (bytes or a binary file object / stream) and `staged_file_id`; exactly one video source is allowed.
|
|
21
|
+
- `PostUploadError.headers` exposes the response headers.
|
|
22
|
+
|
|
23
|
+
### Platforms and responses
|
|
24
|
+
|
|
25
|
+
- Six new platforms: `devto`, `hashnode`, `lemmy`, `nostr`, `whop`, `listmonk` (22 in total) in `PLATFORMS` and `CREDENTIAL_PLATFORMS`, with optional credential fields in the new `CREDENTIAL_OPTIONAL_FIELDS`.
|
|
26
|
+
- `data.skipped_platforms` (platforms the file is too large for) is typed (`SkippedPlatform`, `UploadResponse`) and returned by the new `get_skipped_platforms(response)` helper.
|
|
27
|
+
- Response `TypedDict`s are exported and the package ships `py.typed`.
|
|
28
|
+
|
|
29
|
+
## 1.1.0
|
|
30
|
+
|
|
31
|
+
- Typed methods for the full REST API, typed errors, explicit `User-Agent`.
|
|
32
|
+
- Discord, Telegram, Slack, Mastodon and WordPress, and `connect_with_credentials()`.
|
|
33
|
+
- Class renamed `IndReelForge` (`InReelForge` kept as an alias).
|
|
34
|
+
|
|
35
|
+
## 1.0.0
|
|
36
|
+
|
|
37
|
+
- First release.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 IndReelForge
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,548 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: post-upload
|
|
3
|
+
Version: 1.2.0
|
|
4
|
+
Summary: Official Python SDK for Post-Upload — one API to post to 22 platforms: Instagram, YouTube, TikTok, Facebook, X, LinkedIn, Threads, Pinterest, Reddit, Bluesky, Google Business Profile, Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop & Listmonk
|
|
5
|
+
Home-page: https://post-upload.com
|
|
6
|
+
Author: Post-Upload
|
|
7
|
+
Author-email: support@post-upload.com
|
|
8
|
+
Project-URL: Homepage, https://post-upload.com
|
|
9
|
+
Project-URL: Documentation, https://docs.post-upload.com
|
|
10
|
+
Project-URL: Source, https://github.com/Indreelforge/indreelforge-python
|
|
11
|
+
Project-URL: Bug Tracker, https://github.com/Indreelforge/indreelforge-python/issues
|
|
12
|
+
Keywords: social-media-api,instagram-api,youtube-api,tiktok-api,facebook-api,twitter-api,linkedin-api,threads-api,pinterest-api,reddit-api,bluesky-api,google-business-profile-api,social-media-posting,video-upload,post-upload,indreelforge,mcp,model-context-protocol,ai-agents,discord-api,telegram-api,slack-api,mastodon-api,wordpress-api,devto-api,hashnode-api,lemmy-api,nostr,whop-api,listmonk
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
25
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
26
|
+
Requires-Python: >=3.8
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
License-File: LICENSE
|
|
29
|
+
Requires-Dist: requests>=2.28.0
|
|
30
|
+
Provides-Extra: test
|
|
31
|
+
Requires-Dist: pytest>=7; extra == "test"
|
|
32
|
+
Dynamic: author
|
|
33
|
+
Dynamic: author-email
|
|
34
|
+
Dynamic: classifier
|
|
35
|
+
Dynamic: description
|
|
36
|
+
Dynamic: description-content-type
|
|
37
|
+
Dynamic: home-page
|
|
38
|
+
Dynamic: keywords
|
|
39
|
+
Dynamic: license-file
|
|
40
|
+
Dynamic: project-url
|
|
41
|
+
Dynamic: provides-extra
|
|
42
|
+
Dynamic: requires-dist
|
|
43
|
+
Dynamic: requires-python
|
|
44
|
+
Dynamic: summary
|
|
45
|
+
|
|
46
|
+
# Post-Upload — Python SDK
|
|
47
|
+
|
|
48
|
+
[](https://pypi.org/project/post-upload/)
|
|
49
|
+
[](https://pypi.org/project/post-upload/)
|
|
50
|
+
[](https://opensource.org/licenses/MIT)
|
|
51
|
+
|
|
52
|
+
Official Python SDK for the [Post-Upload](https://post-upload.com) API. Publish videos, photos, text and documents to **22 platforms** with a single API call: **Instagram, YouTube, TikTok, Facebook, X (Twitter), LinkedIn, Threads, Pinterest, Reddit, Bluesky, Google Business Profile, Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop & Listmonk**.
|
|
53
|
+
|
|
54
|
+
> **Moving from the `indreelforge` package?** The SDK was renamed with the product. Run `pip uninstall indreelforge && pip install post-upload`, then import from `post_upload`. Old code keeps running: this package still ships an `indreelforge` module (with a `DeprecationWarning`), and `IndReelForge` / `IndReelForgeError` are aliases of `PostUpload` / `PostUploadError`. The `indreelforge` package on PyPI gets no further updates. See [Upgrading](#upgrading).
|
|
55
|
+
|
|
56
|
+
## Installation
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
pip install post-upload
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Requires Python 3.8+. The only dependency is `requests`.
|
|
63
|
+
|
|
64
|
+
## Quick start
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from post_upload import PostUpload
|
|
68
|
+
|
|
69
|
+
client = PostUpload(api_key="your-api-key-here") # or set POST_UPLOAD_API_KEY
|
|
70
|
+
|
|
71
|
+
result = client.upload_video(
|
|
72
|
+
user="my-profile",
|
|
73
|
+
platforms=["instagram", "tiktok", "youtube"],
|
|
74
|
+
video_path="./my-video.mp4",
|
|
75
|
+
title="Check out this video!",
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
print(result["data"]["upload_id"])
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Configuration
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
client = PostUpload(
|
|
85
|
+
api_key="your-api-key", # Dashboard → API Keys. Default: $POST_UPLOAD_API_KEY
|
|
86
|
+
base_url="https://api.post-upload.com", # Optional (default)
|
|
87
|
+
timeout=120, # Optional, seconds per request (default 120)
|
|
88
|
+
session=None, # Optional requests.Session
|
|
89
|
+
headers={"X-Trace": "abc"}, # Optional extra headers
|
|
90
|
+
chunked_threshold=None, # Optional, bytes (default 95 MiB), see "Large videos"
|
|
91
|
+
max_retries=5, # Optional, retries per failed chunk
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
# Or as a context manager, which closes the HTTP session afterwards:
|
|
95
|
+
with PostUpload() as client: # key from POST_UPLOAD_API_KEY
|
|
96
|
+
print(client.get_me())
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Without `api_key` the client reads `POST_UPLOAD_API_KEY` (or the older `INDREELFORGE_API_KEY`). Every request sends `Authorization: Apikey <key>` and an explicit `User-Agent: post-upload-python/<version>`. (The API sits behind Cloudflare, which blocks generic agents such as `Python-urllib`; if you call the REST API without this SDK, set your own User-Agent.)
|
|
100
|
+
|
|
101
|
+
## Publishing
|
|
102
|
+
|
|
103
|
+
### Common upload options
|
|
104
|
+
|
|
105
|
+
All `upload_*` methods accept:
|
|
106
|
+
|
|
107
|
+
| Argument | API field | Description |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| `user` | `user` | Profile name (required) |
|
|
110
|
+
| `platforms` | `platform[]` | `instagram`, `youtube`, `tiktok`, `facebook`, `x`, `linkedin`, `threads`, `pinterest`, `reddit`, `bluesky`, `google_business`, `discord`, `telegram`, `slack`, `mastodon`, `wordpress`, `devto`, `hashnode`, `lemmy`, `nostr`, `whop`, `listmonk` (also exported as `PLATFORMS`) |
|
|
111
|
+
| `title` | `title` | Title / caption |
|
|
112
|
+
| `description` | `description` | Long description |
|
|
113
|
+
| `first_comment` | `first_comment` | First comment |
|
|
114
|
+
| `schedule` | `schedule` | ISO-8601 datetime to publish later |
|
|
115
|
+
| `timezone` | `timezone` | IANA timezone for `schedule` |
|
|
116
|
+
| `add_to_queue` | `add_to_queue` | Put the post in the profile's next free queue slot |
|
|
117
|
+
| `async_upload` | `async_upload` | `False` = wait (up to ~50 s) for the publish result |
|
|
118
|
+
| `request_id` | `request_id` | Your own correlation id (see `get_request_status`) |
|
|
119
|
+
| `idempotency_key` | `Idempotency-Key` header | Retries with the same key never double-post |
|
|
120
|
+
| `platform_options` / `**kwargs` | any | Platform-specific fields, sent as-is (see below) |
|
|
121
|
+
|
|
122
|
+
### Upload a video
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
# From a local file
|
|
126
|
+
client.upload_video(
|
|
127
|
+
user="my-profile",
|
|
128
|
+
platforms=["instagram", "tiktok", "youtube", "facebook"],
|
|
129
|
+
video_path="./video.mp4",
|
|
130
|
+
title="My video",
|
|
131
|
+
first_comment="#socialmedia",
|
|
132
|
+
schedule="2026-12-01T10:00:00Z",
|
|
133
|
+
youtube_privacy="public",
|
|
134
|
+
youtube_tags="tutorial,tech",
|
|
135
|
+
idempotency_key="video-2026-12-01",
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
# From a public URL (the server downloads it, up to 500 MB)
|
|
139
|
+
client.upload_video(
|
|
140
|
+
user="my-profile",
|
|
141
|
+
platforms=["tiktok"],
|
|
142
|
+
video_url="https://cdn.example.com/clip.mp4",
|
|
143
|
+
)
|
|
144
|
+
|
|
145
|
+
# From bytes or an open binary file / stream
|
|
146
|
+
with open("./video.mp4", "rb") as f:
|
|
147
|
+
client.upload_video(user="my-profile", platforms=["x"], video_file=f, title="Clip")
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Give the video in exactly one way: `video_path`, `video_file`, `video_url` or `staged_file_id`.
|
|
151
|
+
|
|
152
|
+
### Large videos (chunked upload, up to 500 MB)
|
|
153
|
+
|
|
154
|
+
Requests reach the API through Cloudflare, which caps one request at 100 MB. **Local files larger than 95 MiB are sent in parts automatically**: the SDK starts an upload session, sends each part (sequentially, exactly the server's `chunk_size`, retrying on `429`, `5xx` and network errors with backoff and `Retry-After`), completes it and posts the result by `staged_file_id`. Files are read part by part, never loaded whole into memory. If anything fails after the session started, the session is cancelled and the error is raised.
|
|
155
|
+
|
|
156
|
+
```python
|
|
157
|
+
def progress(sent, total):
|
|
158
|
+
print(f"{sent * 100 // total}%")
|
|
159
|
+
|
|
160
|
+
client.upload_video(
|
|
161
|
+
user="my-profile",
|
|
162
|
+
platforms=["youtube", "facebook"],
|
|
163
|
+
video_path="./full-episode.mp4", # e.g. 380 MB
|
|
164
|
+
title="Full episode",
|
|
165
|
+
on_progress=progress, # called after each part
|
|
166
|
+
)
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
`chunked=True` forces the chunked path for any size, `chunked=False` disables it. To upload once and post later, or to drive the parts yourself:
|
|
170
|
+
|
|
171
|
+
```python
|
|
172
|
+
staged = client.upload_large_file("./full-episode.mp4", on_progress=progress)
|
|
173
|
+
client.upload_video("my-profile", ["youtube"], staged_file_id=staged, title="Full episode")
|
|
174
|
+
|
|
175
|
+
# Low level (POST/PUT/GET/DELETE /api/upload/chunked/...)
|
|
176
|
+
s = client.create_upload_session("episode.mp4", size, "video/mp4")
|
|
177
|
+
# -> upload_session_id, chunk_size (32 MiB), total_chunks, expires_at (6 hours)
|
|
178
|
+
for i in range(s["total_chunks"]):
|
|
179
|
+
client.upload_part(s["upload_session_id"], i, read_part(i, s["chunk_size"]))
|
|
180
|
+
client.get_upload_session(s["upload_session_id"]) # received_chunks, to resume
|
|
181
|
+
staged = client.complete_upload_session(s["upload_session_id"])["staged_file_id"]
|
|
182
|
+
# client.abort_upload_session(s["upload_session_id"]) # cancel
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
A staged file can be posted once, only by the account (and workspace) that uploaded it. Chunked upload is for videos (MP4, MOV, AVI, WebM, MKV); at most 5 sessions can be in progress per account.
|
|
186
|
+
|
|
187
|
+
### Skipped platforms
|
|
188
|
+
|
|
189
|
+
Each platform has its own maximum file size (for example Bluesky 100 MB, Discord 10 MB). Platforms the file is too large for are **skipped**: the post goes to the others, and the skipped ones are marked `failed` with `FILE_TOO_LARGE_FOR_PLATFORM` and listed in `data.skipped_platforms`. `get_skipped_platforms()` returns that list (or `[]`):
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
from post_upload import get_skipped_platforms
|
|
193
|
+
|
|
194
|
+
res = client.upload_video("my-profile", ["youtube", "bluesky"], video_path="./big.mp4")
|
|
195
|
+
for s in get_skipped_platforms(res):
|
|
196
|
+
print(s["platform"], s["message"]) # also: error_code, file_size_mb, max_size_mb
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Only when no selected platform can take the file is the request refused (`413 FILE_TOO_LARGE_FOR_PLATFORM`). The response types are exported as `TypedDict`s (`UploadResponse`, `SkippedPlatform`, `UploadSession`, …) for type checkers.
|
|
200
|
+
|
|
201
|
+
### Upload photos
|
|
202
|
+
|
|
203
|
+
Local files, public URLs, or both — up to 10 in total.
|
|
204
|
+
|
|
205
|
+
```python
|
|
206
|
+
client.upload_photos(
|
|
207
|
+
user="my-profile",
|
|
208
|
+
platforms=["instagram", "facebook", "pinterest"],
|
|
209
|
+
photo_paths=["./photo1.jpg"],
|
|
210
|
+
photo_urls=["https://cdn.example.com/photo2.jpg"],
|
|
211
|
+
title="Photo carousel",
|
|
212
|
+
platform_options={"pinterest_board_id": "1234567890"},
|
|
213
|
+
)
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### Text post
|
|
217
|
+
|
|
218
|
+
```python
|
|
219
|
+
client.upload_text(
|
|
220
|
+
user="my-profile",
|
|
221
|
+
platforms=["x", "threads", "bluesky", "linkedin"],
|
|
222
|
+
text="Just shipped a new feature!", # `title=` still works as in 1.0
|
|
223
|
+
)
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
### Document post (LinkedIn)
|
|
227
|
+
|
|
228
|
+
```python
|
|
229
|
+
client.upload_document(
|
|
230
|
+
user="my-profile",
|
|
231
|
+
document_path="./deck.pdf", # PDF, PPT, PPTX, DOC, DOCX (max 100 MB)
|
|
232
|
+
title="Q4 results",
|
|
233
|
+
visibility="PUBLIC",
|
|
234
|
+
target_linkedin_page_id="12345", # optional: post as a company page
|
|
235
|
+
)
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
### Synchronous mode
|
|
239
|
+
|
|
240
|
+
By default an upload returns immediately and publishes in the background. With `async_upload=False` the server waits up to about 50 seconds and returns the outcome:
|
|
241
|
+
|
|
242
|
+
```python
|
|
243
|
+
res = client.upload_text(user="my-profile", platforms=["bluesky"], text="hi", async_upload=False)
|
|
244
|
+
if res.get("sync"):
|
|
245
|
+
print(res["data"]["status"], res["data"]["platforms"], res["data"]["platform_post_ids"])
|
|
246
|
+
else:
|
|
247
|
+
# Took longer than the wait window: poll instead
|
|
248
|
+
print(client.get_upload_status(res["data"]["upload_id"]))
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Platform-specific options
|
|
252
|
+
|
|
253
|
+
Pass any platform-specific API field through `platform_options` (or as extra keyword arguments). Lists are sent as repeated fields, booleans as `"true"`/`"false"`, dicts as JSON.
|
|
254
|
+
|
|
255
|
+
```python
|
|
256
|
+
client.upload_photos(
|
|
257
|
+
user="my-profile",
|
|
258
|
+
platforms=["tiktok", "google_business", "reddit"],
|
|
259
|
+
photo_urls=["https://cdn.example.com/menu.jpg"],
|
|
260
|
+
title="New menu is live",
|
|
261
|
+
platform_options={
|
|
262
|
+
"privacy_level": "PUBLIC_TO_EVERYONE", # TikTok
|
|
263
|
+
"auto_add_music": True,
|
|
264
|
+
"gbp_location_id": "locations/123", # Google Business Profile
|
|
265
|
+
"gbp_cta_type": "LEARN_MORE",
|
|
266
|
+
"gbp_cta_url": "https://example.com",
|
|
267
|
+
"reddit_subreddit": "food", # Reddit
|
|
268
|
+
},
|
|
269
|
+
)
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Use the platform helper methods below to look up page, board and location ids.
|
|
273
|
+
|
|
274
|
+
**Per-platform text overrides (every platform).** `<platform>_title` and `<platform>_description` replace the shared `title` / `description` for that platform only, e.g. `x_title`, `linkedin_description`, `mastodon_title`, `wordpress_description`.
|
|
275
|
+
|
|
276
|
+
**Mastodon**
|
|
277
|
+
|
|
278
|
+
| Field | Values |
|
|
279
|
+
|---|---|
|
|
280
|
+
| `mastodon_visibility` | `public` (default), `unlisted`, `private` or `direct` |
|
|
281
|
+
| `mastodon_spoiler_text` | Content warning shown before the post |
|
|
282
|
+
| `mastodon_sensitive` | `True` to mark media as sensitive. Omit it otherwise: the server treats any non-empty value, including `"false"`, as true |
|
|
283
|
+
| `mastodon_alt_text` | Alt text for attached media (defaults to the title) |
|
|
284
|
+
| `mastodon_language` | ISO 639 language code, e.g. `"en"` |
|
|
285
|
+
|
|
286
|
+
**WordPress**
|
|
287
|
+
|
|
288
|
+
| Field | Values |
|
|
289
|
+
|---|---|
|
|
290
|
+
| `wordpress_status` | `publish` (default) or `draft` |
|
|
291
|
+
| `wordpress_categories` | Numeric category IDs: `"3,7"` or `[3, 7]` |
|
|
292
|
+
| `wordpress_tags` | Numeric tag IDs: `"12,15"` or `[12, 15]` |
|
|
293
|
+
|
|
294
|
+
```python
|
|
295
|
+
client.upload_text(
|
|
296
|
+
user="my-profile",
|
|
297
|
+
platforms=["mastodon", "wordpress", "slack"],
|
|
298
|
+
text="Release notes",
|
|
299
|
+
description="Full changelog for 1.1 …",
|
|
300
|
+
platform_options={
|
|
301
|
+
"mastodon_title": "Release notes are out (short version for Mastodon)",
|
|
302
|
+
"mastodon_visibility": "unlisted",
|
|
303
|
+
"mastodon_language": "en",
|
|
304
|
+
"wordpress_status": "draft",
|
|
305
|
+
"wordpress_categories": [3, 7],
|
|
306
|
+
"wordpress_tags": "12,15",
|
|
307
|
+
},
|
|
308
|
+
)
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
## Connect platforms with credentials
|
|
312
|
+
|
|
313
|
+
Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop and Listmonk connect with credentials instead of an OAuth login. `connect_with_credentials(profile, platform, credentials=None, **fields)` sends them to the API, which verifies them live with the platform before saving them (encrypted). Connecting again replaces the stored credentials. Pass the fields as a dict, as keyword arguments, or both (keyword arguments win):
|
|
314
|
+
|
|
315
|
+
| Platform | Fields (`?` = optional) |
|
|
316
|
+
|---|---|
|
|
317
|
+
| `discord` | `webhook_url` — channel webhook URL |
|
|
318
|
+
| `telegram` | `bot_token`, `chat_id` — token from @BotFather; public channel `@username` or numeric chat ID |
|
|
319
|
+
| `slack` | `webhook_url` — incoming webhook URL (Slack can only verify it on the first post) |
|
|
320
|
+
| `mastodon` | `instance_url`, `access_token` — e.g. `https://mastodon.social`; token with `write:statuses` and `write:media` |
|
|
321
|
+
| `wordpress` | `site_url`, `username`, `app_password` — self-hosted site, a user who can publish, an application password |
|
|
322
|
+
| `devto` | `api_key`, `base_url?` — DEV API key (Settings → Extensions); `base_url` only for another Forem site |
|
|
323
|
+
| `hashnode` | `access_token`, `publication_id` — personal access token; the publication needs a Hashnode Pro plan |
|
|
324
|
+
| `lemmy` | `instance_url`, `username`, `password`, `community`, `totp?` — community as `name` or `name@instance`; `totp` only with 2FA (used once, not stored) |
|
|
325
|
+
| `nostr` | `nsec`, `relays?`, `blossom_server?` — `nsec1…` or hex key; comma-separated `wss://` relays; Blossom server for photos |
|
|
326
|
+
| `whop` | `api_key` + **one of** `experience_id` (forum, `exp_…`) or `channel_id` (chat) |
|
|
327
|
+
| `listmonk` | `base_url`, `api_user`, `api_token`, `list_ids` — API user with campaigns:manage, campaigns:send, lists:get_all, media:manage; list IDs comma-separated |
|
|
328
|
+
|
|
329
|
+
```python
|
|
330
|
+
from post_upload import PostUploadError
|
|
331
|
+
|
|
332
|
+
res = client.connect_with_credentials("my-profile", "telegram", bot_token="123456789:AA…", chat_id="@mychannel")
|
|
333
|
+
print(res["platform_username"])
|
|
334
|
+
|
|
335
|
+
client.connect_with_credentials("my-profile", "devto", api_key="…")
|
|
336
|
+
client.connect_with_credentials("my-profile", "whop", api_key="…", experience_id="exp_XXXXXXXX")
|
|
337
|
+
|
|
338
|
+
try:
|
|
339
|
+
client.connect_with_credentials(
|
|
340
|
+
"my-profile", "mastodon", {"instance_url": "https://mastodon.social", "access_token": "bad"}
|
|
341
|
+
)
|
|
342
|
+
except PostUploadError as e:
|
|
343
|
+
if e.status_code == 400:
|
|
344
|
+
# e.code: "MISSING_FIELD" | "FIELD_TOO_LONG" | "INVALID_CREDENTIALS"
|
|
345
|
+
print(e.code, (e.body.get("details") or {}).get("field"), e)
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
Other failures: `404` (profile not found) and `502` (the platform could not be reached to verify the details). The required fields per platform are also exported as `CREDENTIAL_PLATFORMS`, the optional ones as `CREDENTIAL_OPTIONAL_FIELDS`.
|
|
349
|
+
|
|
350
|
+
## All methods
|
|
351
|
+
|
|
352
|
+
| Area | Method | Endpoint |
|
|
353
|
+
|---|---|---|
|
|
354
|
+
| Upload | `upload_video(user, platforms, video_path=None, ..., video_url=None, video_file=None, staged_file_id=None, chunked=None, on_progress=None)` | `POST /api/upload` (+ chunked endpoints for large files) |
|
|
355
|
+
| | `upload_photos(user, platforms, photo_paths=None, ..., photo_urls=None)` | `POST /api/upload_photos` |
|
|
356
|
+
| | `upload_text(user, platforms, title=None, ..., text=None)` | `POST /api/upload_text` |
|
|
357
|
+
| | `upload_document(user, document_path, title=None, ...)` | `POST /api/upload_document` |
|
|
358
|
+
| Chunked upload | `upload_large_file(video, filename=None, mime_type=None, on_progress=None)` → `staged_file_id` | init + parts + complete |
|
|
359
|
+
| | `create_upload_session(filename, size, mime_type=None)` | `POST /api/upload/chunked/init` |
|
|
360
|
+
| | `upload_part(session_id, index, data, retries=None)` | `PUT /api/upload/chunked/:id/:index` |
|
|
361
|
+
| | `complete_upload_session(session_id)` | `POST /api/upload/chunked/:id/complete` |
|
|
362
|
+
| | `get_upload_session(session_id)` | `GET /api/upload/chunked/:id` |
|
|
363
|
+
| | `abort_upload_session(session_id)` | `DELETE /api/upload/chunked/:id` |
|
|
364
|
+
| Account | `get_me()` | `GET /api/me` |
|
|
365
|
+
| Uploads | `get_upload_status(upload_id)` | `GET /api/upload/:id/status` |
|
|
366
|
+
| | `get_request_status(request_id)` | `GET /api/uploadposts/status?request_id=` |
|
|
367
|
+
| | `list_uploads(limit=None, page=None, status=None)` | `GET /api/uploads` |
|
|
368
|
+
| | `get_upload(upload_id)` | `GET /api/uploads/:id` |
|
|
369
|
+
| | `delete_upload(upload_id)` | `DELETE /api/uploads/:id` |
|
|
370
|
+
| | `retry_upload(upload_id)` | `POST /api/uploads/:id/retry` |
|
|
371
|
+
| | `get_platform_limits()` | `GET /api/platform-limits` |
|
|
372
|
+
| Profiles | `get_profiles()` | `GET /api/profiles` |
|
|
373
|
+
| | `create_profile(name)` | `POST /api/profiles` |
|
|
374
|
+
| | `delete_profile(name)` | `DELETE /api/profiles/:name` |
|
|
375
|
+
| | `connect_with_credentials(profile, platform, credentials=None, **fields)` | `POST /api/profiles/:name/connect/:platform/credentials` |
|
|
376
|
+
| Schedule | `get_scheduled_posts()` | `GET /api/schedule` |
|
|
377
|
+
| | `update_scheduled_post(job_id, scheduled_date=None, timezone=None, title=None, caption=None)` | `PATCH /api/schedule/:jobId` |
|
|
378
|
+
| | `cancel_scheduled_post(job_id)` | `DELETE /api/schedule/:jobId` |
|
|
379
|
+
| Queue | `get_queue_settings(profile)` | `GET /api/queue/settings` |
|
|
380
|
+
| | `update_queue_settings(profile, slots=None, days_of_week=None, timezone=None, max_posts_per_slot=None)` | `POST /api/queue/settings` |
|
|
381
|
+
| | `get_queue_preview(profile, count=None)` | `GET /api/queue/preview` |
|
|
382
|
+
| | `get_next_queue_slot(profile)` | `GET /api/queue/next-slot` |
|
|
383
|
+
| Platform helpers | `get_facebook_pages(profile)` | `GET /api/platforms/facebook/pages` |
|
|
384
|
+
| | `get_linkedin_pages(profile)` | `GET /api/platforms/linkedin/pages` |
|
|
385
|
+
| | `get_pinterest_boards(profile)` | `GET /api/platforms/pinterest/boards` |
|
|
386
|
+
| | `get_google_business_locations(profile)` | `GET /api/platforms/google-business/locations` |
|
|
387
|
+
| Analytics | `get_analytics(range="30d")` | `GET /api/analytics/overview` |
|
|
388
|
+
| | `get_live_analytics(profile, platforms=None)` | `GET /api/analytics/live/:profile` |
|
|
389
|
+
| | `get_post_analytics(upload_id, platform=None)` | `GET /api/analytics/post/:upload_id` |
|
|
390
|
+
| | `get_total_impressions(profile, platform=None, period=None, start_date=None, end_date=None)` | `GET /api/analytics/total-impressions/:profile` |
|
|
391
|
+
| FFmpeg | `get_ffmpeg_usage()` | `GET /api/ffmpeg/usage` |
|
|
392
|
+
| | `list_ffmpeg_jobs()` | `GET /api/ffmpeg/jobs` |
|
|
393
|
+
| | `get_ffmpeg_job(job_id)` | `GET /api/ffmpeg/jobs/:jobId` |
|
|
394
|
+
| Plans | `get_plans()` | `GET /api/plans` |
|
|
395
|
+
|
|
396
|
+
Examples:
|
|
397
|
+
|
|
398
|
+
```python
|
|
399
|
+
me = client.get_me() # plan + monthly usage
|
|
400
|
+
failed = client.list_uploads(status="failed", limit=10)["uploads"]
|
|
401
|
+
if failed:
|
|
402
|
+
client.retry_upload(failed[0]["id"])
|
|
403
|
+
|
|
404
|
+
client.update_queue_settings(
|
|
405
|
+
"my-profile",
|
|
406
|
+
slots=["09:00", "17:30"],
|
|
407
|
+
days_of_week=[1, 2, 3, 4, 5],
|
|
408
|
+
timezone="Europe/London",
|
|
409
|
+
)
|
|
410
|
+
client.upload_video("my-profile", ["youtube"], "./v.mp4", add_to_queue=True)
|
|
411
|
+
|
|
412
|
+
posts = client.get_scheduled_posts()["scheduled_posts"]
|
|
413
|
+
client.update_scheduled_post(posts[0]["id"], scheduled_date="2026-12-24T09:00:00Z")
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
## Error handling
|
|
417
|
+
|
|
418
|
+
Every API failure raises `PostUploadError` (`IndReelForgeError` is the same class):
|
|
419
|
+
|
|
420
|
+
| Attribute | Description |
|
|
421
|
+
|---|---|
|
|
422
|
+
| `status_code` (alias `status`) | HTTP status (`0` = network error, `408` = client-side timeout) |
|
|
423
|
+
| `code` | API error code (`error_code` / `code`), e.g. `MISSING_VIDEO`, or `NETWORK_ERROR` / `TIMEOUT` |
|
|
424
|
+
| `body` | Parsed response body (dict) or raw text |
|
|
425
|
+
| `headers` | Response headers (`None` for network errors), e.g. `Retry-After` |
|
|
426
|
+
| `str(err)` | Human-readable message from the API |
|
|
427
|
+
|
|
428
|
+
```python
|
|
429
|
+
from post_upload import PostUploadError
|
|
430
|
+
|
|
431
|
+
try:
|
|
432
|
+
client.upload_video(user="my-profile", platforms=["tiktok"], video_path="./v.mp4")
|
|
433
|
+
except PostUploadError as e:
|
|
434
|
+
print(f"API error {e.status_code} ({e.code}): {e}", e.body)
|
|
435
|
+
except FileNotFoundError as e:
|
|
436
|
+
print(f"File not found: {e}")
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
Invalid arguments (for example neither `video_path` nor `video_url`, or more than 10 photos) raise `ValueError` before any request is made.
|
|
440
|
+
|
|
441
|
+
## MCP: use Post-Upload from AI agents
|
|
442
|
+
|
|
443
|
+
Post-Upload runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server, so Claude, ChatGPT, Cursor and other agents can publish posts, check upload status and read analytics with your API key. No Python is needed for this.
|
|
444
|
+
|
|
445
|
+
**Hosted URL (Streamable HTTP)** — for clients that support remote MCP servers with headers:
|
|
446
|
+
|
|
447
|
+
- URL: `https://api.post-upload.com/mcp`
|
|
448
|
+
- Header: `Authorization: ApiKey your-api-key`
|
|
449
|
+
|
|
450
|
+
**stdio clients (Claude Desktop, Cursor)** — use the bridge from the [Node.js package](https://www.npmjs.com/package/post-upload) (requires Node.js 18+):
|
|
451
|
+
|
|
452
|
+
```json
|
|
453
|
+
{
|
|
454
|
+
"mcpServers": {
|
|
455
|
+
"post-upload": {
|
|
456
|
+
"command": "npx",
|
|
457
|
+
"args": ["-y", "post-upload", "mcp"],
|
|
458
|
+
"env": {
|
|
459
|
+
"POST_UPLOAD_API_KEY": "your-api-key"
|
|
460
|
+
}
|
|
461
|
+
}
|
|
462
|
+
}
|
|
463
|
+
}
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
See the [Node.js SDK README](https://github.com/Indreelforge/indreelforge-node) and the [MCP guide](https://docs.post-upload.com/guides/mcp-server) for all MCP options. Agents that can't stream large files through MCP can pass a public `video_url` (up to 500 MB).
|
|
467
|
+
|
|
468
|
+
## Supported platforms
|
|
469
|
+
|
|
470
|
+
| Platform | Video | Photo | Text | Document | Scheduling |
|
|
471
|
+
|----------|-------|-------|------|----------|------------|
|
|
472
|
+
| Instagram | ✓ | ✓ | - | - | ✓ |
|
|
473
|
+
| YouTube | ✓ | - | - | - | ✓ |
|
|
474
|
+
| TikTok | ✓ | ✓ | - | - | ✓ |
|
|
475
|
+
| Facebook | ✓ | ✓ | ✓ | - | ✓ |
|
|
476
|
+
| X (Twitter) | ✓ | ✓ | ✓ | - | ✓ |
|
|
477
|
+
| LinkedIn | ✓ | ✓ | ✓ | ✓ | ✓ |
|
|
478
|
+
| Threads | ✓ | ✓ | ✓ | - | ✓ |
|
|
479
|
+
| Pinterest | ✓ | ✓ | - | - | ✓ |
|
|
480
|
+
| Reddit | ✓ | ✓ | ✓ | - | ✓ |
|
|
481
|
+
| Bluesky | ✓ | ✓ | ✓ | - | ✓ |
|
|
482
|
+
| Google Business Profile | - | ✓ | ✓ | - | ✓ |
|
|
483
|
+
| Discord | ✓ | ✓ | ✓ | - | ✓ |
|
|
484
|
+
| Telegram | ✓ | ✓ | ✓ | - | ✓ |
|
|
485
|
+
| Slack | - | - | ✓ | - | ✓ |
|
|
486
|
+
| Mastodon | ✓ | ✓ | ✓ | - | ✓ |
|
|
487
|
+
| WordPress | ✓ | ✓ | ✓ | - | ✓ |
|
|
488
|
+
| Dev.to | - | - | ✓ | - | ✓ |
|
|
489
|
+
| Hashnode | - | ✓ | ✓ | - | ✓ |
|
|
490
|
+
| Lemmy | - | ✓ | ✓ | - | ✓ |
|
|
491
|
+
| Nostr | - | ✓ | ✓ | - | ✓ |
|
|
492
|
+
| Whop | ✓ | ✓ | ✓ | - | ✓ |
|
|
493
|
+
| Listmonk | - | ✓ | ✓ | - | ✓ |
|
|
494
|
+
|
|
495
|
+
Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop and Listmonk are connected with [credentials](#connect-platforms-with-credentials); the others connect through an OAuth login in the dashboard (or an app password for Bluesky).
|
|
496
|
+
|
|
497
|
+
## Upgrading
|
|
498
|
+
|
|
499
|
+
### From `indreelforge` (1.1 and earlier) to `post-upload` 1.2
|
|
500
|
+
|
|
501
|
+
```bash
|
|
502
|
+
pip uninstall indreelforge
|
|
503
|
+
pip install post-upload
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
```python
|
|
507
|
+
# before
|
|
508
|
+
from indreelforge import IndReelForge, IndReelForgeError
|
|
509
|
+
client = IndReelForge(api_key="...")
|
|
510
|
+
|
|
511
|
+
# after
|
|
512
|
+
from post_upload import PostUpload, PostUploadError
|
|
513
|
+
client = PostUpload(api_key="...")
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
Nothing else changes: methods, arguments and return values are the same. Until you update your imports, `import indreelforge` keeps working from the `post-upload` package (it warns with `DeprecationWarning`), and `IndReelForge`, `InReelForge`, `IndReelForgeError` and `InReelForgeError` remain aliases of the new names. The default API address is now `https://api.post-upload.com` (the old address keeps working while the move completes), and the key can come from `POST_UPLOAD_API_KEY` (`INDREELFORGE_API_KEY` is still read).
|
|
517
|
+
|
|
518
|
+
Don't keep both packages installed: both provide an `indreelforge` module.
|
|
519
|
+
|
|
520
|
+
### From 1.0 to 1.1
|
|
521
|
+
|
|
522
|
+
1.1 is backward compatible: existing method names, positional arguments and return values keep working.
|
|
523
|
+
|
|
524
|
+
- The class was renamed `IndReelForge` (now `PostUpload`); `InReelForge` is still exported as an alias.
|
|
525
|
+
- The exception is `IndReelForgeError`; `InReelForgeError` is an alias, so `except InReelForgeError` still works.
|
|
526
|
+
- Uploads are always sent as `multipart/form-data`, and file handles are closed after each request.
|
|
527
|
+
- `upload_text` sends your text as `text` (the API treats `text` and `title` the same).
|
|
528
|
+
|
|
529
|
+
## Development
|
|
530
|
+
|
|
531
|
+
```bash
|
|
532
|
+
python -m venv .venv
|
|
533
|
+
.venv/bin/pip install -e ".[test]"
|
|
534
|
+
.venv/bin/python -m pytest
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
## Links
|
|
538
|
+
|
|
539
|
+
- [Website](https://post-upload.com)
|
|
540
|
+
- [API documentation](https://docs.post-upload.com)
|
|
541
|
+
- [Dashboard](https://post-upload.com/dashboard)
|
|
542
|
+
- [Pricing](https://post-upload.com/pricing)
|
|
543
|
+
- [Node.js SDK & MCP bridge](https://www.npmjs.com/package/post-upload)
|
|
544
|
+
- [Changelog](https://github.com/Indreelforge/indreelforge-python/blob/main/CHANGELOG.md)
|
|
545
|
+
|
|
546
|
+
## License
|
|
547
|
+
|
|
548
|
+
MIT
|