Tiktok Slideshow

GET /api/v1/slideshows/{id}
Response: { "id": "uuid", "title": "...", "slides": [...], "status": "draft", "previewUrl": "..." }

PUT /api/v1/slideshows/{id}
Body: { "title": "New Title", "slides": [...], "status": "ready_to_publish" }
Response: { "id": "uuid", "title": "New Title", ... }

{
  "id": "slide-uuid",
  "imageUrl": "https://cdn.viralbaby.co/...",
  "aspectRatio": "3:4",
  "textElements": [
    { "text": "Your hook text here", "type": "title", "fontSize": 16 },
    { "text": "Supporting subtitle", "type": "subtitle", "fontSize": 14 }
  ]
}

DELETE /api/v1/slideshows/{id}
Response: { "success": true }

POST /api/v1/slideshows/{id}/render
Body: { "slideIndices": [1, 3] }   // optional (1-indexed), defaults to all slides
Response: { "renderedSlides": [{ "index": 1, "url": "https://s3.../rendered-slide.jpg" }] }

GET /api/v1/tiktok/connect
Response: {
  "authUrl": "https://www.tiktok.com/v2/auth/authorize/?...",
  "message": "Open this URL in any browser to connect your TikTok account."
}

GET /api/v1/tiktok/status
Response: { "connected": true, "tokenExpired": false, "user": { "display_name": "..." } }
// or
Response: { "connected": false, "message": "TikTok not connected..." }

POST /api/v1/tiktok/upload
Body: {
  "slideshowId": "uuid",
  "title": "5 Morning Routine Tips",
  "description": "I used to wake up exhausted every single day. Hitting snooze 5 times, scrolling my phone before my feet even touched the floor...\n\nThen I made 3 small changes and everything shifted. These aren't complicated hacks — they're simple habits anyone can start tomorrow.\n\nSave this for your morning tomorrow 👇",
  "hashtags": ["morningroutine", "productivity", "tips"]
}
Response: { "success": true, "publishId": "tiktok-publish-id", "renderedSlides": 5 }

0. Check credentials (in order):
   a. If $VB_KEY is set → skip to step 1
   b. If $VB_PASSWORD is set → POST /api/v1/auth { "email": "...", "password": "$VB_PASSWORD" } → export VB_KEY="vb_live_..."
   c. Otherwise → POST /api/v1/auth { "email": "...", "password": "<auto-generate>", "action": "signup" } → export VB_KEY="vb_live_..." && export VB_PASSWORD="..."

0b. Fetch preferences
   GET /api/v1/preferences
   → If style or product_info is null, ask user and save with PUT /api/v1/preferences
   → Use stored context for all content decisions going forward

1. Search for images
   POST /api/v1/images/search  { "query": "morning routine aesthetic" }
   → save searchId

2. Create a collection from search results
   POST /api/v1/collections/from-search  { "name": "Morning Routine", "searchId": "...", "imageIndices": [1, 3, 6, 9, 12] }
   → save collectionId

3. Create the slideshow (one slide per element in the array, up to 30 slides)
   POST /api/v1/slideshows  {
     "title": "5 Morning Routine Tips",
     "aspectRatio": "3:4",
     "slides": [
       { "collectionId": "...", "textElements": [{ "text": "Your morning routine is broken", "type": "title" }] },
       { "collectionId": "...", "textElements": [{ "text": "Tip #1: Wake up at the same time", "type": "title" }, { "text": "Consistency beats motivation", "type": "subtitle" }] },
       { "collectionId": "...", "textElements": [{ "text": "Tip #2: No phone for 30 min", "type": "title" }] },
       { "collectionId": "...", "textElements": [{ "text": "Tip #3: Move your body", "type": "title" }] },
       { "collectionId": "...", "textElements": [{ "text": "Follow for more tips", "type": "title" }] }
     ]
   }
   → save slideshowId, get previewUrl

4. (Optional) Edit slides
   GET /api/v1/slideshows/{id}  → get current slides
   Modify text/elements as needed, then:
   PUT /api/v1/slideshows/{id}  { "slides": [...updated slides...] }

5. Preview the slideshow
   Share previewUrl with the user so they can verify in their browser

6. Connect TikTok (first time only)
   GET /api/v1/tiktok/connect  → give authUrl to user to open in browser → complete OAuth
   GET /api/v1/tiktok/status   → verify connected: true

7. Upload to TikTok drafts
   POST /api/v1/tiktok/upload  { "slideshowId": "...", "title": "5 Morning Routine Tips", "description": "I used to wake up and immediately reach for my phone...\n\n(write a long, detailed caption — 500-2000+ chars)", "hashtags": ["morningroutine", "productivity"] }
   → Tell user to open TikTok app to review and publish from drafts

GET /api/v1/billing
Authorization: Bearer $VB_KEY
Response: {
  "plan": "free",
  "uploadCount": 3,
  "limit": 5,
  "upgradeUrl": "https://viralbaby.co/checkout?userId=user_xxx"
}

HTTP 402
{
  "error": "Free upload limit reached. Upgrade to Pro for unlimited uploads.",
  "plan": "free",
  "uploadCount": 5,
  "limit": 5,
  "upgradeUrl": "https://viralbaby.co/checkout?userId=user_xxx"
}

{ "plan": "pro", "uploadCount": 5, "limit": "unlimited" }

POST /api/v1/feedback
Body: { "type": "error", "message": "POST /api/v1/tiktok/upload returned 500: Internal server error. Slideshow ID: abc123" }
Body: { "type": "feedback", "message": "User says: would love to be able to change font styles" }

{ "error": "Human-readable error message" }