@upload-post/ai-sdk

Upload-Post tools for the Vercel AI SDK. They let an AI agent publish videos, photos and text to TikTok, Instagram, YouTube, LinkedIn, Facebook, X, Threads, Pinterest, Bluesky, Discord and Telegram, schedule posts, check their status, and read analytics.

The tools are built on the official upload-post SDK and work with AI SDK 6 and 7.

Installation

npm install @upload-post/ai-sdk ai zod

Get an API key at app.upload-post.com/api-keys and connect your social accounts to a profile. Then set the key:

UPLOAD_POST_API_KEY=your-api-key

Usage

import { generateText, isStepCount } from 'ai';
import { uploadPostTools } from '@upload-post/ai-sdk';

const { text } = await generateText({
  model: 'openai/gpt-5-mini',
  tools: uploadPostTools(),
  stopWhen: isStepCount(5),
  prompt:
    'Publish https://example.com/launch.mp4 to TikTok and Instagram for my profile "acme" with a catchy caption, then tell me the request id.',
});

console.log(text);

uploadPostTools() returns every tool. They share one API client and go straight into tools of generateText, streamText or a ToolLoopAgent.

Tools

Tool	What it does
uploadVideo	Publish a video by public URL, now, at a date, or in the next queue slot
uploadPhotos	Publish one or more images (carousel) by public URL
uploadText	Publish a text post (X, LinkedIn, Facebook, Threads, Bluesky, Discord, Telegram)
getUploadStatus	Progress and per-platform result of an upload (request_id) or scheduled post (job_id)
listScheduledPosts	Posts scheduled or queued for the future, filterable by profile and date range
cancelScheduledPost	Cancel a scheduled post and refund its credits
getUploadHistory	Past uploads with post URLs and error messages
listProfiles	Profiles and the social accounts connected to each
getAnalytics	Account analytics (followers, impressions, reach…) per platform

Uploads run asynchronously by default: uploadVideo and uploadPhotos return a request_id straight away, and the agent calls getUploadStatus to follow them. Scheduled and queued posts return a job_id.

Options

uploadPostTools({
  apiKey: 'your-api-key',  // default: process.env.UPLOAD_POST_API_KEY
  profile: 'acme',          // pin every tool to one Upload-Post profile
  needsApproval: true,      // ask a human before publishing or cancelling
});

• apiKey: falls back to the UPLOAD_POST_API_KEY environment variable.
• profile: without it, the model passes the profile username (user) on each call and can find it with listProfiles. With it, the user input disappears, every call uses this profile, and the listing tools only return its data. This is the safe choice for a multi-tenant app: give each end user a toolset pinned to their own profile.
• needsApproval: turns on AI SDK tool approval for uploadVideo, uploadPhotos, uploadText and cancelScheduledPost. Read-only tools never ask.
• client: pass your own new UploadPost(key) instance (or a mock in tests).

Individual tools

Every tool is also exported on its own and takes the same options:

import { uploadVideo, getUploadStatus } from '@upload-post/ai-sdk';

const tools = {
  uploadVideo: uploadVideo({ profile: 'acme' }),
  getUploadStatus: getUploadStatus(),
};

Media must be public URLs

The tools accept http(s) URLs only, for videos, images, covers and thumbnails. Local file paths are rejected on purpose: the model writes these values, and the underlying SDK would read any path it received from disk and upload it. To publish a local file, upload it to your storage first or call the upload-post SDK directly.

Platform options

The upload tools take the most useful per-network settings as nested objects, for example:

{
  "videoUrl": "https://example.com/clip.mp4",
  "platforms": ["tiktok", "youtube", "x"],
  "title": "Behind the scenes",
  "platformTitles": { "x": "Behind the scenes 🎬" },
  "tiktok": { "privacyLevel": "PUBLIC_TO_EVERYONE" },
  "youtube": { "privacyStatus": "unlisted", "tags": ["bts"] },
  "scheduledDate": "2026-12-01T10:00:00",
  "timezone": "Europe/Madrid"
}

The full parameter reference is in the Upload-Post API docs: upload video, upload photos, upload text.

Development

npm install
npm test          # vitest, the SDK is mocked
npm run typecheck
npm run build     # tsup: ESM + CJS + .d.ts

npm run example runs examples/generate-text.ts against the real API. It only reads data (profiles and scheduled posts). Copy .env.example to .env and fill in UPLOAD_POST_API_KEY and AI_GATEWAY_API_KEY first.

Links

• Upload-Post
• API documentation
• upload-post SDK

License

MIT