Upload Photos

Upload photos to various social media platforms using this endpoint.

Note: This feature is a work in progress. More parameters and social media platforms will be added in future updates.

Endpoint

POST /api/upload_photos

Headers

Name	Value	Description
Authorization	Apikey your-api-key-here	Your API key for authentication

Common Parameters

Name	Type	Required	Description
user	String	Yes	User identifier
platform[]	Array	Yes	Platform(s) to upload to. Supported values: tiktok, instagram, linkedin, facebook, x, threads, pinterest
photos[]	Array	Yes	Array of photo files to upload (can be file uploads or photo URLs)
title	String	Yes	Default title of the post
caption	String	No	Caption/description for the photos (this will be used as the post commentary)
scheduled_date	String (ISO-8601)	No	Optional date/time (ISO-8601) to schedule publishing, e.g., "2024-12-31T23:45:00Z". Must be in the future (≤ 365 days). Omit for immediate upload.

This endpoint supports simultaneous photo uploads to multiple social media platforms.

Platform-Specific Titles

The title parameter serves as a fallback. To set a custom title for a particular platform, use the optional [platform]_title parameter. If provided, it will override the main title for that platform.

Example Optional Parameters:

• instagram_title: "Check out my latest reel on Instagram! #reels"
• facebook_title: "Excited to share this new video with my Facebook friends and family."
• tiktok_title: "New TikTok video just dropped! 🔥"
• linkedin_title: "A professional insight on the latest industry trends, discussed in this video."
• x_title: "New video out now! 📢"

Platform-Specific Parameters

LinkedIn

Name	Type	Required	Description	Default
linkedin_title	String	No	Specific title for the LinkedIn post. Fallbacks to title.	title
visibility	String	No	Visibility setting for the post (accepted value: "PUBLIC")	PUBLIC
target_linkedin_page_id	String	No	LinkedIn page ID to upload photos to an organization	"107579166"

Note: The caption is used as the post commentary; no separate description is accepted.

Facebook

Name	Type	Required	Description	Default
facebook_title	String	No	Specific title for the Facebook post. Fallbacks to title.	title
facebook_page_id	String	Yes	Facebook Page ID where the photos will be posted	-
facebook_media_type	String	No	Type of media ("POSTS" or "STORIES")	"POSTS"

Note: The caption is applied only to the first photo uploaded. For correct posting on Facebook, ensure the Page is directly associated with your personal profile and not managed through a Business Portfolio.

X (Twitter)

Name	Type	Required	Description	Default
x_title	String	No	Specific title for the tweet. Fallbacks to title.	title
x_long_text_as_post	Boolean	No	When true, publishes long text as a single post. Otherwise, creates a thread.	false

Note: For Twitter uploads, specify the platform as "x" in the platform[] array.

How X (Twitter) Thread Creation Works (Advanced Logic)

Note: The following describes the default thread creation logic. To override this and post long text as a single post, set the x_long_text_as_post parameter to true.

The system is engineered to create well-formatted, natural-looking threads on X (formerly Twitter). Instead of simply splitting text at every line break, it intelligently groups paragraphs to create more readable tweets.

Here's the step-by-step logic:

Intelligent Paragraph Grouping (Primary Method):

The function first identifies distinct paragraphs (any text separated by a blank line). It then combines as many of these paragraphs as possible into a single tweet, filling it up to the 280-character limit without exceeding it. The double newline (\n\n) between combined paragraphs is preserved for formatting. This results in fewer, more substantial tweets that flow naturally, just as if a person had written them.

Handling Exceptionally Long Paragraphs:

If a single paragraph is, by itself, longer than the 280-character limit, a more granular splitting logic is automatically triggered for that paragraph only:

• Split by Line Break: The system first attempts to break the paragraph down by its individual line breaks (\n).
• Split by Word: If any of those single lines are still too long, it will split them by words as a final resort.

Media Attachment:

For posts that include photos or videos, all media is attached only to the first tweet of the thread. The subsequent tweets in the thread will be text-only replies.

TikTok

Name	Type	Required	Description	Default
tiktok_title	String	No	Specific title for the TikTok post. Fallbacks to title.	title
auto_add_music	Boolean	No	Automatically add background music to photos	false
disable_comment	Boolean	No	Disable comments on the post	false
branded_content	Boolean	No	Indicate if the post is branded content (requires disclose_commercial=true)	false
disclose_commercial	Boolean	No	Disclose the commercial nature of the post (used with branded_content)	false
photo_cover_index	Integer	No	Index (starting at 0) of the photo to use as the cover/thumbnail for the TikTok photo post	0
description	String	No	Description for the TikTok post. If not provided, the title value will be used by default.	title

Note: Setting branded_content along with disclose_commercial to true will enable specific branded content toggles on TikTok.

Instagram

Name	Type	Required	Description	Default
instagram_title	String	No	Specific title for the Instagram post. Fallbacks to title.	title
media_type	String	No	Type of media ("IMAGE" or "STORIES")	"IMAGE"

Threads

Name	Type	Required	Description	Default
threads_title	String	No	Specific title for the Threads post. Fallbacks to title.	title

Pinterest

Name	Type	Required	Description	Default
pinterest_title	String	No	Specific title for the Pinterest Pin. Fallbacks to title.	title
pinterest_board_id	String	Yes	Pinterest board ID to publish the photo to.	-
pinterest_alt_text	String	No	Alt text for the image.	-
pinterest_link	String	No	Destination link for the photo Pin.	-

Example Requests

Upload Photos to Instagram

curl \
  -H 'Authorization: Apikey your-api-key-here' \
  -F 'photos[]=@/path/to/your/image1.jpg' \
  -F 'user="test"' \
  -F 'platform[]=instagram' \
  -F 'title="My Photo Title"' \
  -F 'description="My photo description"' \
  -X POST https://api.upload-post.com/api/upload_photos

Upload Photos to Facebook Using URLs

curl \
  -H 'Authorization: Apikey your-api-key-here' \
  -F 'photos[]="https://example.com/images/photo1.jpg"' \
  -F 'photos[]="https://example.com/images/photo2.jpg"' \
  -F 'user="test"' \
  -F 'platform[]=facebook' \
  -F 'facebook_page_id="123456789"' \
  -F 'title="My Photo Title"' \
  -F 'caption="Check out these photos!"' \
  -X POST https://api.upload-post.com/api/upload_photos

Response Format

TikTok Response

When uploading photos to TikTok, the API returns the following response structure:

{
  "results": {
    "tiktok": {
      "publish_id": "string",
      "status": "PUBLISH_COMPLETE",
      "success": true,
      "url": "https://www.tiktok.com/@username/photo/publish_id"
    }
  },
  "success": true,
  "usage": {
    "count": 25,
    "last_reset": "2025-05-31T19:09:09.984073",
    "limit": 120
  }
}

Field	Type	Description
results.tiktok.publish_id	String	Unique identifier for the published post
results.tiktok.status	String	Publishing status (e.g., "PUBLISH_COMPLETE")
results.tiktok.success	Boolean	Indicates if the upload was successful
results.tiktok.url	String	Direct URL to the published TikTok post
success	Boolean	Overall API request success status
usage.count	Number	Current API usage count
usage.last_reset	String	Timestamp of last usage counter reset
usage.limit	Number	API usage limit