Build with the Slidestorm API

Create in 3 core calls, then sync lifecycle status and retry safely when needed. AI-generated images, caption baking, and TikTok delivery workflows are all handled for you.

Beta notice: The Slidestorm API is currently in beta and subject to potentially breaking changes.

How it works

Discover accounts, styles, and credits

List your connected TikTok accounts, browse available image styles and collections, and confirm you have enough credits before generating.

List connected accounts

curl https://slidestorm.ai/api/v1/accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Response:
# {
#   "ok": true,
#   "data": {
#     "accounts": [
#       { "id": "01JT5...", "platform": "tiktok", "username": "mychannel", ... }
#     ]
#   }
# }

Browse image styles

curl https://slidestorm.ai/api/v1/image-styles \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Response:
# {
#   "ok": true,
#   "data": {
#     "styles": [
#       { "id": "01JT5...", "name": "cinematic", "display_name": "Cinematic", "style_prompt": "..." }
#     ]
#   }
# }

Check credits

curl https://slidestorm.ai/api/v1/usage \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Response:
# {
#   "ok": true,
#   "data": {
#     "credits": {
#       "remaining": 47,
#       "subscription_remaining": 30,
#       "pack_remaining": 17,
#       "has_active_subscription": true
#     },
#     "costs": {
#       "slideshow_generation": 1,
#       "image_generation": 3
#     }
#   }
# }

Create a slideshow

Send a prompt and Slidestorm generates captions, images, and assembles the slideshow. Poll until complete.

Create slideshow

curl -X POST https://slidestorm.ai/api/v1/slideshows \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-1" \
  -d '{
    "prompt": "5 practical coffee brewing tips for beginners",
    "slide_count": 5,
    "background_option": "generate",
    "image_style_id": "01JT5..."
  }'

# You can also use "custom_image_style" instead of "image_style_id":
#   "custom_image_style": "warm cinematic lighting"

# Response (201):
# {
#   "ok": true,
#   "data": {
#     "slideshow": { "id": "01JT5...", "title": "Generating...", "status": "generating" },
#     "polling": { "endpoint": "/api/v1/slideshows/01JT5...", "status": "generating" }
#   }
# }

Poll until complete

curl https://slidestorm.ai/api/v1/slideshows/01JT5... \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Poll until data.slideshow.status is "completed", "failed", or "timed_out"
# The response includes generation_summary with per-image progress:
#   "generation_summary": {
#     "total_slides": 5,
#     "completed_images": 3,
#     "failed_images": 0,
#     "pending_images": 2,
#     "missing_images": 0
#   }
# The response also includes diagnostics for timeout analysis:
#   "diagnostics": {
#     "failure_code": null,
#     "timed_out_at": null,
#     "last_progress_at": "2026-04-24T19:03:00.000Z",
#     "timeout_threshold_minutes": 30
#   }
# When status is "completed", check is_postable before posting.

Post to TikTok

Once the slideshow is complete, post it to one or more connected TikTok accounts. Then sync provider status so your client can distinguish uploaded-to-inbox vs publicly posted outcomes.

Create post

curl -X POST https://slidestorm.ai/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "5 coffee tips you need to know",
    "slideshow_id": "01JT5...",
    "accounts": [{ "id": "YOUR_ACCOUNT_ID" }],
    "external_id": "my-post-abc123"
  }'

# Response (201):
# {
#   "ok": true,
#   "data": {
#     "post": {
#       "id": "01JT5...",
#       "type": "slideshow",
#       "platform": "tiktok",
#       "status": "pending",
#       "caption": "5 coffee tips you need to know",
#       "scheduled_at": "2026-04-24T19:00:00.000Z",
#       "created_at": "2026-04-24T19:00:00.000Z",
#       "external_id": "my-post-abc123",
#       "accounts": {
#         "total": 1,
#         "states": [
#           { "account_id": "01JT5...", "status": "pending", ... }
#         ]
#       }
#     },
#     "duplicate": false
#   }
# }

Sync status after create

curl -X POST https://slidestorm.ai/api/v1/posts/01JT5.../check-status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Use data.status fields to drive automation:
# - post_status
# - provider_status
# - is_terminal
# - is_recoverable
#
# uploaded = sent to TikTok inbox for manual publish
# posted = published/completed

Why use the Slidestorm API?

Caption baking handled

TikTok slideshows require text burned into images. Slidestorm renders captions onto your slides with production-quality templates — no rendering pipeline to build.

TikTok API abstracted

OAuth token management, PULL_FROM_URL hosting, creator info queries, post status polling — all handled behind one simple endpoint.

One prompt to posted

Send a text prompt and get a fully generated slideshow with AI images and captions, ready to post. No need to orchestrate multiple AI services.

Idempotent and reliable

Built-in idempotency keys for slideshows and external IDs for posts. Safe to retry on failure without creating duplicates.

Authentication

All API requests require a bearer token with the appropriate abilities:

slidestorm-api:read for GET endpoints
slidestorm-api:write for POST, PATCH, and DELETE endpoints

Create tokens from your account settings. The typical agent workflow needs both abilities. All resource IDs are ULIDs (26-character strings).

curl https://slidestorm.ai/api/v1/accounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Endpoints

All endpoints are prefixed with https://slidestorm.ai/api/v1.

Discovery

GET/accounts— connected TikTok accounts

GET/image-styles— available image generation styles

GET/collections— image collections for library backgrounds

GET/usage— credit balance and costs

Slideshows

POST/slideshows— create a slideshow generation job

GET/slideshows/{id}— get slideshow status and slides

Posts

POST/posts— create a post from a completed slideshow

GET/posts— list posts with optional status filter

GET/posts/{id}— get a post and delivery states

POST/posts/{id}/check-status— sync provider status and update post lifecycle

PATCH/posts/{id}— update a mutable post

POST/posts/{id}/retry— retry failed deliveries

DELETE/posts/{id}— delete a pending or scheduled post

Key concepts

Idempotency

POST /slideshows requires an Idempotency-Key header. Sending the same key with the same payload returns the original response without creating a duplicate. If the same key is sent with a different payload, you'll get a 409 error. POST /posts supports idempotency via the optional external_id field: same payload returns the existing post with duplicate: true, while a different payload returns 409 with error_code=external_id_reused_with_different_payload.

Polling

Slideshow generation is asynchronous. After creating a slideshow, poll GET /slideshows/{id} until status reaches completed, failed, or timed_out. The response includes generation_summary with per-image progress and diagnostics for timeout/debugging context. Check is_postable to confirm the slideshow is ready before calling POST /posts.

Post lifecycle

Post status is aggregate and derived from per-account delivery states. Typical flow is pending → uploaded → posted (or pending → posted in direct completion paths). Use POST /posts/{id}/check-status to sync provider state. A failed status is retryable only when is_recoverable=true.

Response envelope

All API responses use a consistent envelope with ok, code, message, and data (or error_code and issues for errors).

Error response example

{
  "ok": false,
  "code": 422,
  "message": "Invalid payload",
  "error_code": "invalid_payload",
  "issues": {
    "field_errors": {
      "caption": ["The caption field is required."]
    }
  }
}

Slideshow creation options

POST /slideshows accepts the following fields. An Idempotency-Key header is required.

Field	Required	Description
`prompt`	Yes	Topic or instructions for the slideshow
`slide_count`	Yes	Number of slides (1–12)
`background_option`	Yes	`generate`, `library`, or `single`
`image_style_id`	Conditional	Required with `generate` if no `custom_image_style`
`custom_image_style`	Conditional	Free-text style prompt (max 1000 chars). Alternative to `image_style_id`
`collection_id`	Conditional	Required when `background_option` is `library`
`single_image_id`	Conditional	Required when `background_option` is `single`
`reference_image_id`	No	Reference image for style guidance
`influencer_id`	No	Influencer preset for consistent branding
`model`	No	Image generation model override

Managing posts

After creating a post, treat status as a lifecycle: sync provider state, retry recoverable failures, and use PATCH only when you need to change inputs.

List posts (with optional status filter)

curl "https://slidestorm.ai/api/v1/posts?status=failed&page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Valid statuses: pending, scheduled, uploaded, posted, failed, cancelled, partial
# - pending = due-now pending posts
# - scheduled = future pending posts
# - partial = mixed delivery outcomes
#
# Each post includes title/description/caption plus:
# - social_account summary
# - postable summary (id, type, title, preview_image_url)
# - convenience fields (can_check_status, can_link_to_post, tiktok_url)

Retry failed deliveries

curl -X POST https://slidestorm.ai/api/v1/posts/01JT5.../retry \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "account_ids": ["01JT5..."] }'

# account_ids is optional — omit to retry all failed/cancelled deliveries

Sync TikTok status now

curl -X POST https://slidestorm.ai/api/v1/posts/01JT5.../check-status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Response includes data.status with:
# - post_status
# - provider_status
# - is_terminal
# - is_recoverable
# - platform_post_id
# - progress
#
# Note: uploaded means sent to TikTok inbox for manual review,
# not necessarily publicly posted.

Update a mutable post

curl -X PATCH https://slidestorm.ai/api/v1/posts/01JT5... \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "caption": "Updated caption" }'

# Mutable statuses: pending, scheduled, failed, partial
# Updatable fields: caption, accounts, scheduled_at, platform_configurations

Delete a post

curl -X DELETE https://slidestorm.ai/api/v1/posts/01JT5... \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Only pending or scheduled posts can be deleted

Resources

API Reference

Full interactive OpenAPI documentation

OpenAPI Spec

Download the YAML spec for code generation or agent tools

Manage API Tokens

Create and revoke API tokens from your account

All Documentation

Browse all Slidestorm docs