Skip to Content
API ReferenceUpload MediaBluesky

Bluesky Upload API

This section details how to create posts (Text, Image, Video) on Bluesky 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

Validation & Limits

The following limits are enforced by our API when posting to Bluesky. All values align with Bluesky’s official API documentation .

ConstraintLimitNotes
Post Text300 charactersEnforced via UTF-8 character count. Rich text (mentions, links, hashtags) automatically parsed and faceted.
Post Text3000 UTF-8 bytesHard limit on bytes; most ASCII/Latin text stays well under 300 chars.
Images per Post4 maximumPost fails if more than 4 images provided.
Image File Size2 MB eachEnforced at upload. Files exceeding 2 MB are rejected.
Image FormatsJPG, PNG, GIF, WebPAll formats supported by Bluesky’s blob endpoint.
Image Aspect RatioAny (1:1 to 21:9)Bluesky server handles rendering; API does not enforce aspect ratio.
Video File Size100 MB maximumEnforced at upload. Larger files are rejected.
Video FormatsMP4, MOV, WebMCommon formats supported by Bluesky.
Video DurationUp to 3 minutesRecommended by Bluesky (not enforced by us—check Bluesky docs for protocol limits).
Video Alt Text1000 graphemes maximumEnforced when video is posted with alt text.
Content Labelssexual, nudity, porn, graphic-media, !no-unauthenticatedSelf-label values. These flags help users filter content.
LanguagesISO 639-1 codes (e.g. en, fr)Comma-separated list. Used for content discovery; not validated.

Text-Only & Media Posts

  • Text is optional when posting with an image or video.
  • Text is required only for text-only posts (no media).
  • Rich text parsing: The API automatically detects and facets mentions (@handle.bsky.social), links (https://...), and hashtags (#tag).

Requirements

Bluesky Text Requirements

  • Character Limit: 300 characters.
  • Rich Text: Mentions (@handle), links, and hashtags are automatically parsed.
  • Text is optional when posting with an image or video. It is only required for text-only posts.

Bluesky Image Requirements

  • Max Images: 4 per post.
  • Formats: JPG, PNG, GIF, WebP.
  • Size: Max 2 MB per image.
  • Aspect Ratio: Any aspect ratio supported (Bluesky server handles rendering).

Bluesky Video Requirements

  • Formats: MP4, MOV, WebM.
  • Duration: Up to 3 minutes (recommended by Bluesky).
  • Size: Max 100 MB per video.
  • Alt Text: Optional; max 1000 graphemes if provided.

Create Post

Create a new post on Bluesky.

Endpoint

POST /upload

Content-Type

multipart/form-data

Parameters

Common Parameters

ParameterTypeRequiredDescription
accountIdstring/numberYesThe ID of the connected Bluesky account.
asyncstringNoDefault "true". If "false", waits for completion.

Bluesky Specific Parameters

ParameterTypeRequiredDescription
descriptionstringNo*The text content of the post. (*Required for text-only posts, optional when posting with media).
file / photofileNoImage or Video file. Use photo (array) for carousels (max 4).
bluesky_langsstringNoComma-separated language codes (e.g. en,fr) or array.
bluesky_labelsstringNoContent warnings. Values: sexual, nudity, porn, graphic-media, !no-unauthenticated.

Examples

1. Text Post

curl -X POST https://api.multi-upload-tool.com/api/v1/upload \
  -H "x-api-key: YOUR_KEY" \
  -F "accountId=123" \
  -F "description=Hello Bluesky! #api" \
  -F "bluesky_langs=en"

2. Image Post with Content Warning

curl -X POST https://api.multi-upload-tool.com/api/v1/upload \
  -H "x-api-key: YOUR_KEY" \
  -F "accountId=123" \
  -F "file=@image.jpg" \
  -F "description=Sensitive content here" \
  -F "bluesky_labels=nudity"

3. Video Post

curl -X POST https://api.multi-upload-tool.com/api/v1/upload \
  -H "x-api-key: YOUR_KEY" \
  -F "accountId=123" \
  -F "file=@video.mp4" \
  -F "description=My video post"

Example Response

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