TikTok slideshow API

Post TikTok slideshows (photo carousels) through an API or MCP server: the 35-image limit, formats, inbox vs direct mode, example requests, and every error with its fix.

Early access: publishing slideshows to TikTok is built and being tested in the REST API, @turboyap/sdk and the @turboyap/mcp server. It opens to early-access users as TikTok approves Turboyap; public posts need TikTok's audit. Meanwhile, test mode runs the same requests against a simulated TikTok account.

What a TikTok slideshow is

A TikTok slideshow is a photo post with several images that viewers swipe through, usually with a sound playing underneath. TikTok's Content Posting API calls it a photo post with media_type: PHOTO; Turboyap calls it type: "slideshow".

Turboyap uploads your slides once, converts and resizes them for TikTok, and either sends the slideshow to the creator's TikTok inbox to add a sound (the default) or posts it directly.

Limits

What TikTok accepts for this post type. Turboyap's planner checks every one of these before a post is scheduled (the same data as platform rules), and each value links to the TikTok documentation it comes from.

Compare with other platforms in the social media API limits tracker.

Example requests

All three do the same thing: upload the media, preview the post with a dry run, then schedule it. The idempotency key makes retries safe: send the same request again with the same key and you get the original post back, not a second one.

Early access: api.turboyap.com isn't public yet, and @turboyap/sdk and @turboyap/mcp aren't on npm yet. These examples show the API as built.

curl

# 1. Upload each image. The body is the raw file; Content-Type is its type.
curl https://api.turboyap.com/v1/media \
  -H "Authorization: Bearer $TURBOYAP_API_KEY" \
  -H "Content-Type: image/png" \
  -H "X-Filename: slide-1.png" \
  --data-binary @slide-1.png
# → { "media": { "id": "med_…", "width": 1080, "height": 1920, … }, "deduplicated": false }

# 2. Preview. Remove "dry_run" to create and schedule the post.
curl https://api.turboyap.com/v1/posts \
  -H "Authorization: Bearer $TURBOYAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "slideshow",
    "media_ids": ["med_…", "med_…", "med_…"],
    "caption": "Ice cream or frozen dairy dessert? Read the label.",
    "targets": [{ "account_id": "acct_tiktok…", "tiktok": { "mode": "inbox" } }],
    "schedule_at": "2026-10-20T18:00:00-04:00",
    "fit": { "overflow": "truncate" },
    "idempotency_key": "tiktok-slideshow-2026-10-20",
    "dry_run": true
  }'

TypeScript with @turboyap/sdk

import { readFile } from "node:fs/promises";
import { TurboyapClient } from "@turboyap/sdk";

const ty = new TurboyapClient({ apiKey: process.env.TURBOYAP_API_KEY! });
const account = (await ty.listAccounts()).find((a) => a.platform === "tiktok")!;

const media_ids: string[] = [];
for (const file of ["slide-1.png", "slide-2.png", "slide-3.png"]) {
  const { media } = await ty.uploadMedia(await readFile(file), { filename: file, contentType: "image/png" });
  media_ids.push(media.id);
}

const post = {
  type: "slideshow" as const,
  media_ids,
  caption: "Ice cream or frozen dairy dessert? Read the label.",
  targets: [{ account_id: account.id, tiktok: { mode: "inbox" as const } }],
  schedule_at: "2026-10-20T18:00:00-04:00",
  fit: { overflow: "truncate" as const },
  idempotency_key: "tiktok-slideshow-2026-10-20",
};

// Preview first: every problem comes back with a fix.
const preview = await ty.createPost({ ...post, dry_run: true });
if (!preview.ok) throw new Error(preview.errors.map((e) => `${e.code}: ${e.fix}`).join("\n"));

const { post: created } = await ty.createPost(post);
console.log(created.targets[0]?.status, created.targets[0]?.next_step);

Claude Code (MCP)

Add the Turboyap MCP server once, with an agent key from your workspace:

claude mcp add turboyap -e TURBOYAP_API_KEY=ty_agent_… -- npx -y @turboyap/mcp

Then ask:

Upload the slides in ~/content/icecream and schedule them as a TikTok slideshow for Tuesday 6pm ET. Use inbox mode so I can add a trending sound. Dry-run first and fix anything TikTok rejects.

The agent calls list_accounts, get_platform_rules, upload_media, create_post with dry_run: true, applies any fixes, calls create_post again to schedule, and reports each account's next_step from get_post. The same server works in Cursor; see the MCP quickstart.

Inbox and direct mode

Direct mode needs a privacy_level the creator allows. auto_add_music only applies to direct posts; in inbox mode you pick the sound in the app.

{
  "account_id": "acct_tiktok…",
  "tiktok": {
    "mode": "direct",
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "auto_add_music": true,
    "cover_index": 0,
    "title": "Read the label"
  }
}

Photos are pulled from Turboyap-hosted URLs on a domain verified with TikTok.

Common errors and fixes

Every error has a code, the field that caused it, and a fix an agent can apply without asking you. A request with several problems returns all of them in issues; a dry run returns them without creating anything.

Errors from TikTok itself appear on the target's error with TikTok's own code. Turboyap retries rate limits and temporary failures with backoff, and marks the account for reconnection when TikTok rejects its token.

Approval and audit

• Level 1, review everything (default): a post an agent schedules starts as pending_approval and waits until a human approves it with a human key (POST /v1/posts/:id/approve). Agent keys can't approve.
• Level 3, full autopilot: agent posts schedule directly. Every action is still logged. Level 2, guardrails, is coming soon.
• On TikTok, autopilot goes to the inbox: TikTok requires a person to pick the privacy level of every direct post, so TikTok targets default to inbox mode. Autopilot posts land in the creator's inbox as drafts unless the post sets direct mode with a privacy_level the creator chose.
• Posts created by humans schedule directly at any level.
• Edits re-open review: if an agent changes the caption or time of an approved post on a level-1 account, it goes back to pending_approval.
• Dry runs show the outcome: each target's status_on_create tells the agent whether the post will wait for approval.
• Audit log: every create, approval, edit, publish and failure is recorded with whether a human or an agent did it, the key id, and the MCP client name. The kill switch (POST /v1/workspace/pause) stops every publish to TikTok and every other platform at once.

Read more in the autonomy dial.

FAQ

Related

• TikTok photo post API
• Instagram carousel API
• Bluesky multi-image post API (beta)
• Telegram album API (beta)
• Discord multi-image message API (beta)
• Post one slideshow to TikTok and Instagram
• REST API reference
• Platform rules
• Social media API limits tracker

This page as markdown: /api/tiktok/slideshow.md. Everything for LLMs: /llms.txt.