upload-post 2.9.0__tar.gz → 2.12.0__tar.gz

{upload_post-2.9.0 → upload_post-2.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: upload-post
-Version: 2.9.0
+Version: 2.12.0
 Summary: Cross-platform social media upload for TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, Discord, Telegram, and X (Twitter)
 Home-page: https://www.upload-post.com/
 Author: Upload-Post
@@ -76,6 +76,8 @@ print(response)
 - ✅ **Posting Queue** - Add posts to your configured queue
 - ✅ **First Comments** - Auto-post first comment after publishing
 - ✅ **Analytics** - Get engagement metrics
+- ✅ **Audience** - Who follows a profile, per platform
+- ✅ **Suggestions** - Hashtags and searches to post about, per platform
 - ✅ **Full Type Hints**
 
 ## API Reference
@@ -97,7 +99,7 @@ response = client.upload_video(
     first_comment="Thanks for watching! 🙏",
     
     # Optional: Platform-specific settings
-    privacy_level="PUBLIC_TO_EVERYONE",  # TikTok
+    disable_comment=False,  # TikTok
     media_type="REELS",  # Instagram
     privacyStatus="public",  # YouTube
     tags=["tutorial", "coding"],  # YouTube
@@ -309,12 +311,247 @@ li_pages = client.get_linkedin_pages("my-profile")
 
 # Get Pinterest boards for a profile
 boards = client.get_pinterest_boards("my-profile")
+
+# TikTok: trending Commercial Music Library tracks
+music = client.get_tiktok_trending_music(
+    "my-profile", genre="POP", country_code="ES", date_range="7DAY"
+)
+
+# TikTok: find a track by song or artist
+found = client.search_tiktok_music("my-profile", q="bad bunny", country_code="ES")
+
+# TikTok: search locations to tag
+locations = client.get_tiktok_locations("my-profile", "Madrid")
+```
+
+### Comments
+
+The same methods cover every platform that has comments — Instagram, Facebook,
+YouTube, LinkedIn and TikTok. There is no per-network method: the endpoint
+answers one question and `platform` says who to ask.
+
+```python
+# Read the comments on a post. TikTok has no post-URL lookup: pass the video id.
+comments = client.get_post_comments(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    limit=20,
+)
+
+# Read the replies hanging from one of them — same question, one more parameter
+replies = client.get_post_comments(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    comment_id="7412345678909999999",
+)
+
+# Comment on the post, or reply to a comment
+client.create_comment(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    message="Thanks for watching!",
+)
+client.create_comment(
+    user="my-profile",
+    platform="tiktok",
+    comment_id="7412345678909999999",
+    message="Glad you liked it",
+)
+
+# Delete one
+client.delete_comment(
+    user="my-profile", platform="tiktok", comment_id="7412345678909999999"
+)
+```
+
+You can also have the first comment posted for you right after publishing, with
+`first_comment` for every platform or `tiktok_first_comment` for TikTok alone.
+
+On TikTok all of this needs the `comments` capability, which the account grants
+when it connects — see
+[What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
+
+#### Moderating a comment: hide, like, pin
+
+`comment_action()` does the three and undoes them, on any platform that
+supports it. Each action carries its own inverse, and `post_id` is only sent
+when the platform needs it:
+
+```python
+client.comment_action(
+    user="my-profile", platform="tiktok", action="hide",
+    comment_id="7412345678909999999", post_id="7412345678901234567",
+)
+client.comment_action(
+    user="my-profile", platform="tiktok", action="like",
+    comment_id="7412345678909999999",
+)
+client.comment_action(
+    user="my-profile", platform="tiktok", action="unpin",
+    comment_id="7412345678909999999", post_id="7412345678901234567",
+)
+```
+
+| `action` | Undo | `post_id` |
+| --- | --- | --- |
+| `hide` | `unhide` | required |
+| `like` | `unlike` | not sent |
+| `pin` | `unpin` | required |
+
+### Audience
+
+Where the analytics methods answer *how did my posts do*, `get_audience()`
+answers *who is following me*. One endpoint, one `platform` parameter, like
+every other question in the API.
+
+```python
+audience = client.get_audience(
+    user="my-profile",
+    platform="tiktok",
+    start_date="2026-07-01",
+    end_date="2026-07-30",
+)
+
+print(audience["range"])                 # the window actually used
+print(audience["audience"]["countries"])  # and "cities", "ages", "genders"
+print(audience["activity_by_hour"])       # [{"hour": "14", "followers_online": 1494}, ...]
+print(audience["followers_daily"])        # [{"date", "total", "new", "lost"}, ...]
+print(audience["profile_actions"])        # bio link, address, email, phone, leads
+print(audience["bio_description"])
+```
+
+The window is clamped on the server: at most 60 days, and `end_date` always
+before today. A wider window is trimmed to what the platform accepts instead of
+failing.
+
+Ask for a `benchmark_category` and the same call also returns how the account
+compares with the average of that category. The accepted categories come back in
+`benchmark_categories` on every response, so a picker needs no second call:
+
+```python
+categories = client.get_audience(
+    user="my-profile", platform="tiktok"
+)["benchmark_categories"]
+
+benchmark = client.get_audience(
+    user="my-profile", platform="tiktok",
+    benchmark_category="SOFTWARE_AND_APPS",
+)["benchmark"]
+print(benchmark["average_engagement_rate"], benchmark["average_video_views"])
 ```
 
+### Suggestions
+
+`get_suggestions()` answers *what is worth posting about*: the hashtags or the
+searches a platform suggests around a keyword. One endpoint for both, told apart
+by `type`.
+
+```python
+hashtags = client.get_suggestions(
+    user="my-profile", platform="tiktok", type="hashtags",
+    q="pilates", country_code="ES", language="es",
+)["hashtags"]
+print(hashtags)  # [{"name": ..., "view_count": ...}, ...]
+
+keywords = client.get_suggestions(
+    user="my-profile", platform="tiktok", type="keywords", q="pilates",
+)["keywords"]
+```
+
+Per-post numbers stay in `get_post_analytics()`. On TikTok that response carries
+more than the usual counters: `retention` (the curve, second by second),
+`impression_sources` (For You, search, profile...), `audience_types` (followers
+vs non-followers), `new_followers`, `reach` and the watch times.
+
+Asking a platform a question it cannot answer fails with
+`platform_not_supported` and the list of the ones that can.
+
+## What a TikTok connection can do (`capabilities`)
+
+Not every TikTok connection can do the same things. `client.list_users()`
+(`GET /api/uploadposts/users`) returns a `capabilities` array on each profile's
+TikTok account; check it before offering a feature.
+
+| Capability | What it unlocks |
+| --- | --- |
+| `music` | `tiktok_music_id` and the volume/trim fields, plus `get_tiktok_trending_music()` and `search_tiktok_music()` |
+| `location` | `tiktok_location_id` / `tiktok_location_name`, plus `get_tiktok_locations()` |
+| `cover_image` | `tiktok_cover_image_url` |
+| `cover_timestamp` | `cover_timestamp` |
+| `draft` | `tiktok_upload_to_draft` |
+| `video_privacy` | `privacy_level` on video |
+| `photo_privacy` | `privacy_level` on photo posts |
+| `profile_analytics` | `get_audience()` and `get_suggestions(type="hashtags")` with `platform="tiktok"` |
+| `comments` | Comments on TikTok: `get_post_comments()` (top-level and replies), `create_comment()`, `delete_comment()`, `comment_action()` and `tiktok_first_comment` |
+| `trend_search` | `get_suggestions(type="keywords")` with `platform="tiktok"` |
+
+> **`comments` and `trend_search` need the account to be reconnected.** TikTok
+> grants them at connect time, so an account linked before they existed keeps
+> working for everything else but will not list them — reconnect it from Manage
+> Users to enable them.
+
+If a connection lacks a capability the upload field is simply ignored: the post
+still publishes and the response carries a per-field `warnings` string. The
+methods above answer with an error asking for a reconnection.
+
+## TikTok music, location, cover and drafts
+
+> Needs the `music`, `location`, `cover_image` or `draft` capability — see
+> [What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
+
+```python
+# 1. Pick a track and a place
+tracks = client.get_tiktok_trending_music("my-profile", country_code="ES")["tracks"]
+# ...or find one by name. TikTok has no music search endpoint, so this searches
+# the trending charts Upload-Post caches, not TikTok's whole catalogue.
+tracks = client.search_tiktok_music("my-profile", q="bossa", country_code="ES")["tracks"]
+places = client.get_tiktok_locations("my-profile", "Madrid")["locations"]
+
+# 2. Publish with them
+client.upload_video(
+    "video.mp4",
+    title="Shot in Madrid",
+    user="my-profile",
+    platforms=["tiktok"],
+
+    tiktok_music_id=tracks[0]["id"],
+    tiktok_music_volume=70,             # 0-100, defaults to 50 when music is set
+    tiktok_music_start=0,               # ms
+    tiktok_music_end=15000,             # ms
+    tiktok_original_sound_volume=30,    # 0-100, defaults to 50 so the original audio is not muted
+
+    tiktok_location_id=places[0]["location_id"],
+    tiktok_location_name=places[0]["location_name"],  # required together with the id
+
+    tiktok_cover_image_url="https://example.com/cover.jpg",
+    tiktok_is_ai_generated=False,
+    tiktok_upload_to_draft=False,       # True sends it to drafts and ignores the rest
+)
+```
+
+### TikTok music, location, cover and draft options
+
+| Option | Type | Capability | Notes |
+| --- | --- | --- | --- |
+| `tiktok_music_id` | str | `music` | Video + photos. The track `id` from `get_tiktok_trending_music()` or `search_tiktok_music()` (not `commercial_music_id`) |
+| `tiktok_music_volume` | int | `music` | Video only. 0-100, defaults to 50 when music is set |
+| `tiktok_music_start` | int | `music` | Video only. Music start offset in ms |
+| `tiktok_music_end` | int | `music` | Video only. Music end offset in ms |
+| `tiktok_original_sound_volume` | int | `music` | Video only. 0-100, defaults to 50 when music is set, so the original audio is not muted |
+| `tiktok_location_id` | str | `location` | Video + photos. `location_id` from `get_tiktok_locations()` |
+| `tiktok_location_name` | str | `location` | Required whenever `tiktok_location_id` is set |
+| `tiktok_cover_image_url` | str | `cover_image` | Video only. Custom cover image URL |
+| `tiktok_is_ai_generated` | bool | — | Video + photos. AI-generated content disclosure |
+| `tiktok_upload_to_draft` | bool | `draft` | Video only. Publish to drafts; TikTok ignores the rest of the post settings |
+| `photo_cover_index` | int | — | Cover photo index for photo posts (0-based) |
+| `privacy_level` | str | `photo_privacy` / `video_privacy` | Accepted on video and photo posts alike; which values the account may use is decided by TikTok, see the note below |
+
 ## Platform-Specific Options
 
 ### TikTok (Video)
-- `privacy_level` - PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY
 - `disable_duet` - Disable duet
 - `disable_comment` - Disable comments
 - `disable_stitch` - Disable stitch
@@ -324,10 +561,34 @@ boards = client.get_pinterest_boards("my-profile")
 - `brand_content_toggle` - Branded content toggle
 - `brand_organic_toggle` - Brand organic toggle
 
+> **TikTok particularity:** `privacy_level` works on video and photo posts
+> alike, but **TikTok decides per account which values are available**. A
+> private account, for example, is offered `FOLLOWER_OF_CREATOR`,
+> `MUTUAL_FOLLOW_FRIENDS` and `SELF_ONLY`, with no `PUBLIC_TO_EVERYONE`; asking
+> for one the account does not have fails with
+> `error_code="tiktok_privacy_unavailable"` and an error listing the ones it
+> does have. Omit it on video and TikTok applies the account's own default; on
+> photo posts it defaults to `PUBLIC_TO_EVERYONE`. To offer only the values that
+> will actually work, ask the account with
+> `client.get_tiktok_publishing_settings(profile)` and read
+> `privacy_level_options`.
+
+See [TikTok music, location, cover and drafts](#tiktok-music-location-cover-and-drafts)
+for the music, location, cover and draft options.
+
 ### TikTok (Photos)
+- `privacy_level` - PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY
+- `post_mode` - DIRECT_POST or MEDIA_UPLOAD
 - `auto_add_music` - Auto add music
 - `photo_cover_index` - Index of photo for cover (0-based)
 - `disable_comment` - Disable comments
+- `tiktok_music_id` - Commercial Music Library track id
+- `tiktok_location_id` / `tiktok_location_name` - Location tag, both required together
+- `tiktok_is_ai_generated` - AI-generated content disclosure
+
+> TikTok's photo contract takes the music track id alone: `tiktok_music_volume`,
+> `tiktok_music_start`, `tiktok_music_end`, `tiktok_original_sound_volume`,
+> `tiktok_cover_image_url` and `tiktok_upload_to_draft` are video-only.
 
 ### Instagram
 - `media_type` - REELS, STORIES, IMAGE
@@ -432,6 +693,7 @@ These options work across all upload methods:
 | `user` | Profile name (required) |
 | `platforms` | Target platforms list (required) |
 | `first_comment` | First comment to post |
+| `tiktok_first_comment` | First comment for TikTok only (needs the `comments` capability) |
 | `alt_text` | Alt text for accessibility |
 | `scheduled_date` | ISO date for scheduling |
 | `timezone` | Timezone for scheduled date |

{upload_post-2.9.0 → upload_post-2.12.0}/README.md

@@ -38,6 +38,8 @@ print(response)
 - ✅ **Posting Queue** - Add posts to your configured queue
 - ✅ **First Comments** - Auto-post first comment after publishing
 - ✅ **Analytics** - Get engagement metrics
+- ✅ **Audience** - Who follows a profile, per platform
+- ✅ **Suggestions** - Hashtags and searches to post about, per platform
 - ✅ **Full Type Hints**
 
 ## API Reference
@@ -59,7 +61,7 @@ response = client.upload_video(
     first_comment="Thanks for watching! 🙏",
     
     # Optional: Platform-specific settings
-    privacy_level="PUBLIC_TO_EVERYONE",  # TikTok
+    disable_comment=False,  # TikTok
     media_type="REELS",  # Instagram
     privacyStatus="public",  # YouTube
     tags=["tutorial", "coding"],  # YouTube
@@ -271,12 +273,247 @@ li_pages = client.get_linkedin_pages("my-profile")
 
 # Get Pinterest boards for a profile
 boards = client.get_pinterest_boards("my-profile")
+
+# TikTok: trending Commercial Music Library tracks
+music = client.get_tiktok_trending_music(
+    "my-profile", genre="POP", country_code="ES", date_range="7DAY"
+)
+
+# TikTok: find a track by song or artist
+found = client.search_tiktok_music("my-profile", q="bad bunny", country_code="ES")
+
+# TikTok: search locations to tag
+locations = client.get_tiktok_locations("my-profile", "Madrid")
+```
+
+### Comments
+
+The same methods cover every platform that has comments — Instagram, Facebook,
+YouTube, LinkedIn and TikTok. There is no per-network method: the endpoint
+answers one question and `platform` says who to ask.
+
+```python
+# Read the comments on a post. TikTok has no post-URL lookup: pass the video id.
+comments = client.get_post_comments(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    limit=20,
+)
+
+# Read the replies hanging from one of them — same question, one more parameter
+replies = client.get_post_comments(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    comment_id="7412345678909999999",
+)
+
+# Comment on the post, or reply to a comment
+client.create_comment(
+    user="my-profile",
+    platform="tiktok",
+    post_id="7412345678901234567",
+    message="Thanks for watching!",
+)
+client.create_comment(
+    user="my-profile",
+    platform="tiktok",
+    comment_id="7412345678909999999",
+    message="Glad you liked it",
+)
+
+# Delete one
+client.delete_comment(
+    user="my-profile", platform="tiktok", comment_id="7412345678909999999"
+)
+```
+
+You can also have the first comment posted for you right after publishing, with
+`first_comment` for every platform or `tiktok_first_comment` for TikTok alone.
+
+On TikTok all of this needs the `comments` capability, which the account grants
+when it connects — see
+[What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
+
+#### Moderating a comment: hide, like, pin
+
+`comment_action()` does the three and undoes them, on any platform that
+supports it. Each action carries its own inverse, and `post_id` is only sent
+when the platform needs it:
+
+```python
+client.comment_action(
+    user="my-profile", platform="tiktok", action="hide",
+    comment_id="7412345678909999999", post_id="7412345678901234567",
+)
+client.comment_action(
+    user="my-profile", platform="tiktok", action="like",
+    comment_id="7412345678909999999",
+)
+client.comment_action(
+    user="my-profile", platform="tiktok", action="unpin",
+    comment_id="7412345678909999999", post_id="7412345678901234567",
+)
+```
+
+| `action` | Undo | `post_id` |
+| --- | --- | --- |
+| `hide` | `unhide` | required |
+| `like` | `unlike` | not sent |
+| `pin` | `unpin` | required |
+
+### Audience
+
+Where the analytics methods answer *how did my posts do*, `get_audience()`
+answers *who is following me*. One endpoint, one `platform` parameter, like
+every other question in the API.
+
+```python
+audience = client.get_audience(
+    user="my-profile",
+    platform="tiktok",
+    start_date="2026-07-01",
+    end_date="2026-07-30",
+)
+
+print(audience["range"])                 # the window actually used
+print(audience["audience"]["countries"])  # and "cities", "ages", "genders"
+print(audience["activity_by_hour"])       # [{"hour": "14", "followers_online": 1494}, ...]
+print(audience["followers_daily"])        # [{"date", "total", "new", "lost"}, ...]
+print(audience["profile_actions"])        # bio link, address, email, phone, leads
+print(audience["bio_description"])
+```
+
+The window is clamped on the server: at most 60 days, and `end_date` always
+before today. A wider window is trimmed to what the platform accepts instead of
+failing.
+
+Ask for a `benchmark_category` and the same call also returns how the account
+compares with the average of that category. The accepted categories come back in
+`benchmark_categories` on every response, so a picker needs no second call:
+
+```python
+categories = client.get_audience(
+    user="my-profile", platform="tiktok"
+)["benchmark_categories"]
+
+benchmark = client.get_audience(
+    user="my-profile", platform="tiktok",
+    benchmark_category="SOFTWARE_AND_APPS",
+)["benchmark"]
+print(benchmark["average_engagement_rate"], benchmark["average_video_views"])
 ```
 
+### Suggestions
+
+`get_suggestions()` answers *what is worth posting about*: the hashtags or the
+searches a platform suggests around a keyword. One endpoint for both, told apart
+by `type`.
+
+```python
+hashtags = client.get_suggestions(
+    user="my-profile", platform="tiktok", type="hashtags",
+    q="pilates", country_code="ES", language="es",
+)["hashtags"]
+print(hashtags)  # [{"name": ..., "view_count": ...}, ...]
+
+keywords = client.get_suggestions(
+    user="my-profile", platform="tiktok", type="keywords", q="pilates",
+)["keywords"]
+```
+
+Per-post numbers stay in `get_post_analytics()`. On TikTok that response carries
+more than the usual counters: `retention` (the curve, second by second),
+`impression_sources` (For You, search, profile...), `audience_types` (followers
+vs non-followers), `new_followers`, `reach` and the watch times.
+
+Asking a platform a question it cannot answer fails with
+`platform_not_supported` and the list of the ones that can.
+
+## What a TikTok connection can do (`capabilities`)
+
+Not every TikTok connection can do the same things. `client.list_users()`
+(`GET /api/uploadposts/users`) returns a `capabilities` array on each profile's
+TikTok account; check it before offering a feature.
+
+| Capability | What it unlocks |
+| --- | --- |
+| `music` | `tiktok_music_id` and the volume/trim fields, plus `get_tiktok_trending_music()` and `search_tiktok_music()` |
+| `location` | `tiktok_location_id` / `tiktok_location_name`, plus `get_tiktok_locations()` |
+| `cover_image` | `tiktok_cover_image_url` |
+| `cover_timestamp` | `cover_timestamp` |
+| `draft` | `tiktok_upload_to_draft` |
+| `video_privacy` | `privacy_level` on video |
+| `photo_privacy` | `privacy_level` on photo posts |
+| `profile_analytics` | `get_audience()` and `get_suggestions(type="hashtags")` with `platform="tiktok"` |
+| `comments` | Comments on TikTok: `get_post_comments()` (top-level and replies), `create_comment()`, `delete_comment()`, `comment_action()` and `tiktok_first_comment` |
+| `trend_search` | `get_suggestions(type="keywords")` with `platform="tiktok"` |
+
+> **`comments` and `trend_search` need the account to be reconnected.** TikTok
+> grants them at connect time, so an account linked before they existed keeps
+> working for everything else but will not list them — reconnect it from Manage
+> Users to enable them.
+
+If a connection lacks a capability the upload field is simply ignored: the post
+still publishes and the response carries a per-field `warnings` string. The
+methods above answer with an error asking for a reconnection.
+
+## TikTok music, location, cover and drafts
+
+> Needs the `music`, `location`, `cover_image` or `draft` capability — see
+> [What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
+
+```python
+# 1. Pick a track and a place
+tracks = client.get_tiktok_trending_music("my-profile", country_code="ES")["tracks"]
+# ...or find one by name. TikTok has no music search endpoint, so this searches
+# the trending charts Upload-Post caches, not TikTok's whole catalogue.
+tracks = client.search_tiktok_music("my-profile", q="bossa", country_code="ES")["tracks"]
+places = client.get_tiktok_locations("my-profile", "Madrid")["locations"]
+
+# 2. Publish with them
+client.upload_video(
+    "video.mp4",
+    title="Shot in Madrid",
+    user="my-profile",
+    platforms=["tiktok"],
+
+    tiktok_music_id=tracks[0]["id"],
+    tiktok_music_volume=70,             # 0-100, defaults to 50 when music is set
+    tiktok_music_start=0,               # ms
+    tiktok_music_end=15000,             # ms
+    tiktok_original_sound_volume=30,    # 0-100, defaults to 50 so the original audio is not muted
+
+    tiktok_location_id=places[0]["location_id"],
+    tiktok_location_name=places[0]["location_name"],  # required together with the id
+
+    tiktok_cover_image_url="https://example.com/cover.jpg",
+    tiktok_is_ai_generated=False,
+    tiktok_upload_to_draft=False,       # True sends it to drafts and ignores the rest
+)
+```
+
+### TikTok music, location, cover and draft options
+
+| Option | Type | Capability | Notes |
+| --- | --- | --- | --- |
+| `tiktok_music_id` | str | `music` | Video + photos. The track `id` from `get_tiktok_trending_music()` or `search_tiktok_music()` (not `commercial_music_id`) |
+| `tiktok_music_volume` | int | `music` | Video only. 0-100, defaults to 50 when music is set |
+| `tiktok_music_start` | int | `music` | Video only. Music start offset in ms |
+| `tiktok_music_end` | int | `music` | Video only. Music end offset in ms |
+| `tiktok_original_sound_volume` | int | `music` | Video only. 0-100, defaults to 50 when music is set, so the original audio is not muted |
+| `tiktok_location_id` | str | `location` | Video + photos. `location_id` from `get_tiktok_locations()` |
+| `tiktok_location_name` | str | `location` | Required whenever `tiktok_location_id` is set |
+| `tiktok_cover_image_url` | str | `cover_image` | Video only. Custom cover image URL |
+| `tiktok_is_ai_generated` | bool | — | Video + photos. AI-generated content disclosure |
+| `tiktok_upload_to_draft` | bool | `draft` | Video only. Publish to drafts; TikTok ignores the rest of the post settings |
+| `photo_cover_index` | int | — | Cover photo index for photo posts (0-based) |
+| `privacy_level` | str | `photo_privacy` / `video_privacy` | Accepted on video and photo posts alike; which values the account may use is decided by TikTok, see the note below |
+
 ## Platform-Specific Options
 
 ### TikTok (Video)
-- `privacy_level` - PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY
 - `disable_duet` - Disable duet
 - `disable_comment` - Disable comments
 - `disable_stitch` - Disable stitch
@@ -286,10 +523,34 @@ boards = client.get_pinterest_boards("my-profile")
 - `brand_content_toggle` - Branded content toggle
 - `brand_organic_toggle` - Brand organic toggle
 
+> **TikTok particularity:** `privacy_level` works on video and photo posts
+> alike, but **TikTok decides per account which values are available**. A
+> private account, for example, is offered `FOLLOWER_OF_CREATOR`,
+> `MUTUAL_FOLLOW_FRIENDS` and `SELF_ONLY`, with no `PUBLIC_TO_EVERYONE`; asking
+> for one the account does not have fails with
+> `error_code="tiktok_privacy_unavailable"` and an error listing the ones it
+> does have. Omit it on video and TikTok applies the account's own default; on
+> photo posts it defaults to `PUBLIC_TO_EVERYONE`. To offer only the values that
+> will actually work, ask the account with
+> `client.get_tiktok_publishing_settings(profile)` and read
+> `privacy_level_options`.
+
+See [TikTok music, location, cover and drafts](#tiktok-music-location-cover-and-drafts)
+for the music, location, cover and draft options.
+
 ### TikTok (Photos)
+- `privacy_level` - PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY
+- `post_mode` - DIRECT_POST or MEDIA_UPLOAD
 - `auto_add_music` - Auto add music
 - `photo_cover_index` - Index of photo for cover (0-based)
 - `disable_comment` - Disable comments
+- `tiktok_music_id` - Commercial Music Library track id
+- `tiktok_location_id` / `tiktok_location_name` - Location tag, both required together
+- `tiktok_is_ai_generated` - AI-generated content disclosure
+
+> TikTok's photo contract takes the music track id alone: `tiktok_music_volume`,
+> `tiktok_music_start`, `tiktok_music_end`, `tiktok_original_sound_volume`,
+> `tiktok_cover_image_url` and `tiktok_upload_to_draft` are video-only.
 
 ### Instagram
 - `media_type` - REELS, STORIES, IMAGE
@@ -394,6 +655,7 @@ These options work across all upload methods:
 | `user` | Profile name (required) |
 | `platforms` | Target platforms list (required) |
 | `first_comment` | First comment to post |
+| `tiktok_first_comment` | First comment for TikTok only (needs the `comments` capability) |
 | `alt_text` | Alt text for accessibility |
 | `scheduled_date` | ISO date for scheduling |
 | `timezone` | Timezone for scheduled date |

{upload_post-2.9.0 → upload_post-2.12.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="upload-post",
-    version="2.9.0",
+    version="2.12.0",
     author="Upload-Post",
     author_email="hi@img2html.com",
     description="Cross-platform social media upload for TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, Discord, Telegram, and X (Twitter)",