API v1

TikTok Ruler API docs

Generate account-specific TikTok slideshows, retrieve rendered slide assets, and start TikTok publication workflows from your own backend.

View endpoints Create an API key

Quick start

export TIKTOK_RULER_API_KEY="user_api_key_from_clerk"

curl -s https://tiktok-ruler.com/api/v1/accounts \
  -H "Authorization: Bearer $TIKTOK_RULER_API_KEY"

Base URL

https://tiktok-ruler.com

Authentication

Bearer token from a Clerk user API key.

Generation

Create 3-12 slide TikTok photo-mode concepts.

Publishing

Post generated slideshows to connected TikTok accounts.

Authentication

Use Clerk user API keys

Public API routes accept Clerk user API keys through the Authorization header. Keep keys on your server, never ship them to browsers, mobile clients, or public repositories.

Header format: Authorization: Bearer $TIKTOK_RULER_API_KEY
Recommended labels: accounts:read, slideshows:generate, slideshows:publish
Use idempotency keys on generation and publishing retries.

Auth check

curl -s https://tiktok-ruler.com/api/v1/accounts \
  -H "Authorization: Bearer $TIKTOK_RULER_API_KEY"

Request fields

Generation inputs

These fields are accepted by slideshow generation endpoints.

accountRequired. Account id, account name, or normalized handle.

promptRequired for generation. The creative direction for the slideshow.

contextOptional. Extra audience, product, or campaign context up to 10,000 characters.

contextImagesOptional. Up to 12 image URLs with optional title and description.

referenceImageUrlsOptional legacy shortcut for reference image URLs.

slideCountOptional integer from 3 to 12. Defaults to 6.

imageGenerationEnabledOptional boolean. When true, generated image credits are checked per slide.

qualityOptional. low costs 1 slideshow credit, medium costs 2, high costs 3.

model / models.plannerOptional custom planner model. Do not combine with quality.

idempotencyKeyOptional retry key. The Idempotency-Key and X-Idempotency-Key headers also work.

Endpoints

API reference

All endpoints return JSON. Examples use the production base URL.

GET/api/v1/accounts

List accounts

Returns the TikTok Ruler content creator accounts available to the authenticated API key.

accounts:read

curl

curl -s https://tiktok-ruler.com/api/v1/accounts \
  -H "Authorization: Bearer $TIKTOK_RULER_API_KEY"

Response

{
  "apiVersion": "v1",
  "accounts": [
    {
      "id": "8a7f7d4c-2d4f-4cc3-9f8d-11a8f8c9d3e0",
      "name": "Daily Finds",
      "handle": "dailyfinds",
      "niche": "shopping",
      "tiktok": {
        "connected": true,
        "status": "connected",
        "username": "dailyfinds",
        "displayName": "Daily Finds",
        "avatarUrl": "https://example.com/avatar.jpg"
      }
    }
  ]
}

Use the returned account id, name, or handle in generation requests.

TikTok access tokens are never returned.

POST/api/v1/slideshows/generate

Generate a slideshow

Creates a saved TikTok slideshow for an account and returns the rendered slide images plus caption, hashtags, music, and usage data.

slideshows:generate

Request body

{
  "account": "dailyfinds",
  "prompt": "Create an 8-slide TikTok slideshow about desk upgrades under $50.",
  "context": "Audience: remote workers who like clean setups. Style: practical, fast, slightly dramatic.",
  "contextImages": [
    {
      "url": "https://example.com/desk-lamp.jpg",
      "title": "Desk lamp",
      "description": "Warm adjustable lamp with a small footprint."
    }
  ],
  "slideCount": 8,
  "quality": "medium",
  "imageGenerationEnabled": true,
  "idempotencyKey": "dailyfinds-desk-upgrades-001"
}

curl

curl -s https://tiktok-ruler.com/api/v1/slideshows/generate \
  -H "Authorization: Bearer $TIKTOK_RULER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dailyfinds-desk-upgrades-001" \
  -d '{
    "account": "dailyfinds",
    "prompt": "Create an 8-slide TikTok slideshow about desk upgrades under $50.",
    "slideCount": 8,
    "quality": "medium",
    "imageGenerationEnabled": true
  }'

Response

{
  "apiVersion": "v1",
  "generatedSlideshowId": "5f7d3cb0-2b3f-4d79-97ff-ec75d1dd0932",
  "account": {
    "id": "8a7f7d4c-2d4f-4cc3-9f8d-11a8f8c9d3e0",
    "handle": "dailyfinds",
    "name": "Daily Finds"
  },
  "creditsCharged": 2,
  "credits": {
    "slideshow": 2,
    "imageGeneration": 8,
    "total": 10
  },
  "quality": "medium",
  "title": "Desk Upgrades That Feel Expensive",
  "caption": "Tiny desk changes that make work feel upgraded.",
  "description": "A short product-led slideshow for remote workers.",
  "hashtags": ["desksetup", "remotework", "amazonfinds"],
  "slides": [
    {
      "slideNumber": 1,
      "onScreenText": "Your desk feels cheap because of this one thing",
      "imageDescription": "Clean desk setup with warm lighting",
      "imageSource": "ai_generated",
      "image": {
        "imageUrl": "https://signed-image-url.example",
        "urlKind": "signed",
        "urlExpiresAt": "2026-06-23T12:15:00.000Z",
        "assetId": "image_asset_id",
        "bucket": "media-bucket",
        "objectKey": "rendered-slides/example.png"
      }
    }
  ],
  "music": {
    "mood": "confident",
    "style": "upbeat lifestyle",
    "reason": "Matches fast product reveal pacing."
  },
  "debug": {
    "embeddingDim": 3072,
    "idempotencyKey": "api:user_123:dailyfinds-desk-upgrades-001"
  }
}

Required body fields are account and prompt.

slideCount must be between 3 and 12. The default is 6.

quality can be low, medium, or high. Medium is the default.

contextImages and referenceImageUrls are capped at 12 total images; each imported image URL can be up to 10 MB.

Use idempotencyKey or the Idempotency-Key header to make retries safe.

POST/api/v1/slideshows/generate-and-post

Generate and post

Generates a slideshow, then starts the TikTok publication workflow for the connected account.

slideshows:generate + slideshows:publish

Request body

{
  "account": "dailyfinds",
  "prompt": "Create a 6-slide TikTok slideshow about travel organizers.",
  "slideCount": 6,
  "quality": "medium",
  "publish": {
    "privacyLevel": "SELF_ONLY",
    "disableComment": false,
    "autoAddMusic": true
  },
  "idempotencyKey": "dailyfinds-travel-organizers-001"
}

curl

curl -s https://tiktok-ruler.com/api/v1/slideshows/generate-and-post \
  -H "Authorization: Bearer $TIKTOK_RULER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "dailyfinds",
    "prompt": "Create a 6-slide TikTok slideshow about travel organizers.",
    "slideCount": 6,
    "publish": {
      "privacyLevel": "SELF_ONLY",
      "disableComment": false,
      "autoAddMusic": true
    },
    "idempotencyKey": "dailyfinds-travel-organizers-001"
  }'

Response

{
  "apiVersion": "v1",
  "slideshow": {
    "apiVersion": "v1",
    "generatedSlideshowId": "5f7d3cb0-2b3f-4d79-97ff-ec75d1dd0932",
    "title": "Travel Organizers That Save Your Trip",
    "slides": []
  },
  "publication": {
    "id": "publication_id",
    "generatedSlideshowId": "5f7d3cb0-2b3f-4d79-97ff-ec75d1dd0932",
    "accountId": "8a7f7d4c-2d4f-4cc3-9f8d-11a8f8c9d3e0",
    "provider": "tiktok",
    "postMode": "photo_mode",
    "status": "pending",
    "publishId": null,
    "privacyLevel": "SELF_ONLY",
    "errorMessage": null,
    "createdAt": "2026-06-23T12:00:00.000Z",
    "updatedAt": "2026-06-23T12:00:00.000Z",
    "publishedAt": null
  }
}

The target account must have an active TikTok connection.

Use SELF_ONLY while testing publication behavior.

The publication status may continue changing after the response.

POST/api/v1/slideshows/{generatedSlideshowId}/post

Post an existing slideshow

Starts the TikTok publication workflow for a slideshow that was already generated and saved.

slideshows:publish

Request body

{
  "privacyLevel": "SELF_ONLY",
  "disableComment": false,
  "autoAddMusic": true,
  "idempotencyKey": "post-existing-slideshow-001"
}

curl

curl -s https://tiktok-ruler.com/api/v1/slideshows/5f7d3cb0-2b3f-4d79-97ff-ec75d1dd0932/post \
  -H "Authorization: Bearer $TIKTOK_RULER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "privacyLevel": "SELF_ONLY",
    "disableComment": false,
    "autoAddMusic": true,
    "idempotencyKey": "post-existing-slideshow-001"
  }'

Response

{
  "apiVersion": "v1",
  "publication": {
    "id": "publication_id",
    "generatedSlideshowId": "5f7d3cb0-2b3f-4d79-97ff-ec75d1dd0932",
    "accountId": "8a7f7d4c-2d4f-4cc3-9f8d-11a8f8c9d3e0",
    "provider": "tiktok",
    "postMode": "photo_mode",
    "status": "pending",
    "publishId": null,
    "privacyLevel": "SELF_ONLY",
    "errorMessage": null,
    "createdAt": "2026-06-23T12:00:00.000Z",
    "updatedAt": "2026-06-23T12:00:00.000Z",
    "publishedAt": null
  }
}

The slideshow must belong to the authenticated user.

Set idempotencyKey when retrying a publication request from your backend.

Errors

Status codes

Error responses use a small JSON shape: { "error": "Unauthorized" }.

400Invalid request shape, invalid account selector, or provider validation failure.

401Missing or invalid Clerk user API key.

402The account does not have enough credits for the requested operation.

404Account, slideshow, or publication target was not found for the authenticated user.

500Unexpected server-side failure. Retry with the same idempotency key before creating a duplicate job.