Threads Upload API

This section details how to upload text, images, videos, and carousels to Threads using the API.

Base URL

https://api.multi-upload-tool.com/api/v1

Authentication

All requests require an API Token in the header: x-api-key: YOUR_API_TOKEN

Requirements

Threads Media Requirements

Text Posts

Type: Text-only posts (no media required)
Max length: 500 characters

Image Posts

Supported Formats: JPG, JPEG, PNG, GIF, WEBP
Size: Maximum 8 MB per image
Alt Text: Maximum 1000 characters

Video Posts

Supported Formats: MP4, MOV, AVI, MKV, WebM
Size: Maximum 1 GB (1024 MB)
Processing: Videos are processed asynchronously; expect a delay before publishing

Carousel Posts

Items: Minimum 2, maximum 20 items (mix of images and videos)
Image Size: Maximum 8 MB per image
Video Size: Maximum 1 GB (1024 MB) per video
Alt Text: Maximum 1000 characters (applied to all carousel items)

Validation & Limits

The following limits are enforced by our API:

Constraint	Limit	Notes
Video file size	1 GB (1024 MB)	Enforced by API
Image file size	8 MB per image	Enforced by API
Post text	500 characters	Max character length enforced
Alt text	1000 characters	Max character length for image/video alt text
Carousel items	2–20 items	Minimum 2, maximum 20 per carousel
Reply control	`everyone`, `accounts_you_follow`, `mentioned_only`, `parent_post_author_only`, `followers_only`	Restricts who can reply to the post

Source: Threads API — Content Publishing Guide

Upload Text Post

Upload a text-only post to Threads.

Endpoint

POST /upload

Content-Type

multipart/form-data

Parameters

Query Parameters

Parameter	Type	Required	Description
`async`	string	No	Default `"true"`. If `"false"`, the API waits for upload completion.

Body Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	The ID of the connected Threads account.
`title`	string	Yes	The text content of the post. Maximum 500 characters.
`description`	string	No	Alternative to `title` for the post text.
`threads_reply_control`	string	No	`everyone` (default), `accounts_you_follow`, `mentioned_only`, `parent_post_author_only`, `followers_only`.

Example Request


curl -X POST https://api.multi-upload-tool.com/api/v1/upload \
  -H "x-api-key: YOUR_API_TOKEN" \
  -F "accountId=123" \
  -F "title=Just thinking out loud on Threads 🧵" \
  -F "threads_reply_control=everyone"

Example Response


{
  "success": true,
  "message": "Upload queued successfully",
  "data": {
    "uploadId": 789,
    "status": "pending",
    "jobId": "job_456"
  }
}

Upload Image Post

Upload a single image to Threads.

Endpoint

POST /upload

Content-Type

multipart/form-data

Parameters

Query Parameters

Parameter	Type	Required	Description
`async`	string	No	Default `"true"`. If `"false"`, the API waits for upload completion.

Body Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	The ID of the connected Threads account.
`photo`	File	Yes	The image file (JPG, JPEG, PNG, GIF, WEBP). Maximum 8 MB.
`title`	string	Yes	Post text/caption. Maximum 500 characters.
`description`	string	No	Alternative to `title` for the post text.
`threads_alt_text`	string	No	Accessibility alt text for the image. Maximum 1000 characters.
`threads_reply_control`	string	No	`everyone` (default), `accounts_you_follow`, `mentioned_only`, `parent_post_author_only`, `followers_only`.

Example Request


curl -X POST https://api.multi-upload-tool.com/api/v1/upload \
  -H "x-api-key: YOUR_API_TOKEN" \
  -F "accountId=123" \
  -F "photo=@/path/to/image.jpg" \
  -F "title=Beautiful sunset 🌅" \
  -F "threads_alt_text=A warm golden sunset over the ocean"

Example Response


{
  "success": true,
  "message": "Upload queued successfully",
  "data": {
    "uploadId": 790,
    "status": "pending",
    "jobId": "job_457"
  }
}

Upload Video Post

Upload a single video to Threads.

Endpoint

POST /upload

Content-Type

multipart/form-data

Parameters

Query Parameters

Parameter	Type	Required	Description
`async`	string	No	Default `"true"`. If `"false"`, the API waits for upload completion.

Body Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	The ID of the connected Threads account.
`video`	File	Yes	The video file (MP4, MOV, AVI, MKV, WebM). Maximum 1 GB.
`title`	string	Yes	Post text/caption. Maximum 500 characters.
`description`	string	No	Alternative to `title` for the post text.
`threads_reply_control`	string	No	`everyone` (default), `accounts_you_follow`, `mentioned_only`, `parent_post_author_only`, `followers_only`.

Example Request


curl -X POST https://api.multi-upload-tool.com/api/v1/upload \
  -H "x-api-key: YOUR_API_TOKEN" \
  -F "accountId=123" \
  -F "video=@/path/to/video.mp4" \
  -F "title=Check out this amazing moment! 🎬" \
  -F "threads_reply_control=everyone"

Example Response


{
  "success": true,
  "message": "Upload queued successfully",
  "data": {
    "uploadId": 791,
    "status": "pending",
    "jobId": "job_458"
  }
}

Note: Videos are processed asynchronously by Threads. Publishing may take a few moments.

Upload Carousel

Upload multiple images and/or videos to create a Threads carousel.

Endpoint

POST /upload

Content-Type

multipart/form-data

Parameters

Query Parameters

Parameter	Type	Required	Description
`async`	string	No	Default `"true"`. If `"false"`, the API waits for upload completion.

Body Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	The ID of the connected Threads account.
`photo`	File[]	Yes	Array of image files (JPG, JPEG, PNG, GIF, WEBP). Maximum 8 MB each. Minimum 2, maximum 20 items.
`title`	string	Yes	Post text/caption. Maximum 500 characters.
`description`	string	No	Alternative to `title` for the post text.
`threads_alt_text`	string	No	Accessibility alt text applied to all items. Maximum 1000 characters.
`threads_reply_control`	string	No	`everyone` (default), `accounts_you_follow`, `mentioned_only`, `parent_post_author_only`, `followers_only`.

Example Request


curl -X POST https://api.multi-upload-tool.com/api/v1/upload \
  -H "x-api-key: YOUR_API_TOKEN" \
  -F "accountId=123" \
  -F "photo=@/path/to/image1.jpg" \
  -F "photo=@/path/to/image2.jpg" \
  -F "photo=@/path/to/image3.jpg" \
  -F "title=Photo carousel from the trip ✈️" \
  -F "threads_alt_text=Travel photos from our recent vacation" \
  -F "threads_reply_control=accounts_you_follow"

Example Response


{
  "success": true,
  "message": "Upload queued successfully",
  "data": {
    "uploadId": 792,
    "status": "pending",
    "jobId": "job_459"
  }
}

Carousel limits: Between 2 and 20 items per carousel. Videos and images can be mixed.

Check Upload Status

Check the status of a queued or completed upload. See the Posts API for details on listing and filtering uploads.