TikTok Photo Post API Guide: Carousels, Images & More

TikTok isn't just for videos anymore. Photo posts and carousels (multiple images in a single post) have become powerful formats for creators and brands. If you're building automation, AI agents, or custom integrations, you need to understand how the TikTok photo post API and TikTok carousel API work.

This guide covers everything you need to know: the differences between photo and video posting, step-by-step implementation, code examples, and best practices for image specifications. Whether you're posting single images or multi-photo carousels, you'll have working code by the end.

Photo vs Video Posting: What's Different?

Before diving into implementation, understand the key differences between photo and video content on TikTok:

The TikTok image upload API treats single photos and carousels similarly — both use the same endpoint. The difference is simply how many images you include in the request.

Step-by-Step: Posting a Single Photo

Here's how to post images TikTok API style — programmatically with a simple HTTP request.

Prerequisites

• TikTok account connected to your API provider
• API key for authentication
• Image file (JPG or PNG, under 20MB)

The API Request

curl -X POST https://api.postqued.com/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "tiktok",
    "account_id": "YOUR_TIKTOK_ACCOUNT_ID",
    "content_type": "photo",
    "media_urls": ["https://your-cdn.com/image.jpg"],
    "caption": "Check out this photo! #photo #tiktok",
    "visibility": "public",
    "allow_comments": true,
    "allow_duet": false,
    "allow_stitch": false
  }'

Breaking Down the Request

• content_type: "photo" — Tells TikTok this is an image post
• media_urls — Array of image URLs (single URL for one photo)
• caption — Text description with hashtags
• visibility — public, friends, or private
• Interaction controls — Optional duet, stitch, and comment settings

Response

{
  "success": true,
  "post_id": "post_abc123",
  "status": "pending",
  "platform_post_id": null,
  "scheduled_at": null,
  "published_url": null,
  "message": "Post created and is being processed"
}

The post enters a "pending" state while the image is downloaded and processed. Use webhooks or poll the status endpoint to track progress.

Step-by-Step: Posting Carousels (Multiple Images)

Carousels let users swipe through up to 35 images in a single TikTok post. They're excellent for storytelling, product showcases, and step-by-step tutorials.

The Carousel Request

curl -X POST https://api.postqued.com/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "tiktok",
    "account_id": "YOUR_TIKTOK_ACCOUNT_ID",
    "content_type": "photo",
    "media_urls": [
      "https://your-cdn.com/image1.jpg",
      "https://your-cdn.com/image2.jpg",
      "https://your-cdn.com/image3.jpg",
      "https://your-cdn.com/image4.jpg"
    ],
    "caption": "Step-by-step guide to our new feature 🚀 Swipe through! #tutorial #carousel",
    "visibility": "public",
    "allow_comments": true,
    "allow_duet": false,
    "allow_stitch": false,
    "music_id": "optional-music-track-id"
  }'

Key Differences from Single Photo

• media_urls contains 2-35 URLs (instead of 1)
• Images display in the order provided
• Optional music_id for background audio
• Users swipe horizontally to view all images

JavaScript/TypeScript Example

async function postTikTokCarousel(
  apiKey: string,
  accountId: string,
  imageUrls: string[],
  caption: string
) {
  const response = await fetch('https://api.postqued.com/v1/posts', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      platform: 'tiktok',
      account_id: accountId,
      content_type: 'photo',
      media_urls: imageUrls,
      caption: caption,
      visibility: 'public',
      allow_comments: true,
      allow_duet: false,
      allow_stitch: false,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Failed to create post: ${error.message}`);
  }

  return await response.json();
}

// Usage
const images = [
  'https://cdn.example.com/step1.jpg',
  'https://cdn.example.com/step2.jpg',
  'https://cdn.example.com/step3.jpg',
];

await postTikTokCarousel(
  'your-api-key',
  'your-account-id',
  images,
  'How to get started in 3 easy steps 👆'
);

Python Example

import requests

def post_tiktok_carousel(api_key, account_id, image_urls, caption):
    url = "https://api.postqued.com/v1/posts"
    
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "platform": "tiktok",
        "account_id": account_id,
        "content_type": "photo",
        "media_urls": image_urls,
        "caption": caption,
        "visibility": "public",
        "allow_comments": True,
        "allow_duet": False,
        "allow_stitch": False
    }
    
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    
    return response.json()

# Usage
images = [
    "https://cdn.example.com/product-front.jpg",
    "https://cdn.example.com/product-side.jpg",
    "https://cdn.example.com/product-detail.jpg"
]

result = post_tiktok_carousel(
    api_key="your-api-key",
    account_id="your-account-id",
    image_urls=images,
    caption="New product drop! Swipe to see all angles ✨"
)

print(f"Post created: {result['post_id']}")

Image Specifications & Best Practices

Getting images right is crucial. Poor specs lead to processing failures or low-quality posts.

Required Image Specs

Aspect Ratio Guidelines

TikTok displays photos in a 9:16 vertical format. Images with different ratios get cropped or letterboxed:

• 9:16 (1080x1920) — Full-screen, no cropping
• 4:5 (1080x1350) — Top and bottom cropped
• 1:1 (1080x1080) — Vertical letterboxing
• 16:9 (1920x1080) — Massive cropping, avoid this

Pro tip: Design your images at 1080x1920 to ensure they display exactly as intended.

Image Hosting Requirements

Your images must be accessible via public URLs:

• Use HTTPS — HTTP URLs often fail
• No authentication — The API server needs direct access
• Valid content-type headers — Ensure proper MIME types
• Fast hosting — Slow CDNs can cause timeout errors

Good hosting options: AWS S3 (with public access), Cloudflare R2, Imgur, or your own CDN.

Carousel Best Practices

1. Consistent sizing — Use the same dimensions for all images
2. Logical flow — Order matters; users swipe left to right
3. Text readability — Keep text away from edges (20px safe zone)
4. File size balance — Don't mix 1MB and 15MB images; normalize sizes
5. Caption as context — Use the caption to explain what users should look for

Common Errors & How to Fix Them

"Invalid image format"

Cause: File extension doesn't match actual format, or unsupported format used.

Fix: Convert to JPG/PNG and verify the file isn't corrupted.

"Image too large"

Cause: Single image exceeds 20MB.

Fix: Compress images using tools like TinyPNG, ImageOptim, or Squoosh.

"Failed to download media"

Cause: Image URL returns 404, requires authentication, or times out.

Fix: Test the URL in an incognito browser window. Check that the content-type header is set correctly on your server.

"Unsupported aspect ratio"

Cause: Image dimensions are too extreme (e.g., 100x2000).

Fix: Resize to standard 9:16 ratio. Minimum 540px width, 960px height.

"Too many images"

Cause: More than 35 images in a single post.

Fix: Split into multiple posts or select your best 35 images.

"Carousel processing failed"

Cause: One image in the carousel failed validation.

Fix: Test each image URL individually. Remove problematic images and retry.

Checking Post Status

After creating a photo post, check its status:

curl -X GET https://api.postqued.com/v1/posts/POST_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Status Values

Advanced: Adding Music to Photo Posts

Photo posts can include background music, just like videos:

{
  "content_type": "photo",
  "media_urls": ["https://cdn.example.com/photo.jpg"],
  "music_id": "tiktok-music-track-id",
  "caption": "Photos with music hit different 🎵"
}

To find music IDs, browse TikTok's commercial music library or use trending sounds from the app.

Conclusion

The TikTok photo post API and TikTok carousel API open up powerful automation possibilities. Whether you're building AI agents that generate visual content, bulk-uploading product photos, or creating carousel tutorials programmatically, the process is straightforward:

1. Prepare your images (JPG/PNG, 9:16 ratio, under 20MB)
2. Host them on a public HTTPS URL
3. Send a POST request with your images and caption
4. Monitor status until published

Static API key authentication means your automation runs without human intervention — no OAuth tokens to refresh, no browser automation to maintain. For video posting, see How to Post to TikTok with Python. To add scheduling, follow our guide on scheduling TikTok posts via API. And for a full tool comparison, check the best TikTok scheduler with API.

Ready to start posting photos and carousels programmatically?

Get started with Postqued and make your first TikTok photo post via API in under five minutes.

Last updated: March 2026