ViralBaby API v1 — TikTok Slideshow Creation

Create image carousels with text overlays for TikTok — search images, build slides, edit with AI, and upload to TikTok drafts.

Base URL: https://viralbaby.co

All endpoints (except auth) require: Authorization: Bearer $VB_KEY

---

Authentication & API Key

IMPORTANT — check environment variables first, in this order:

1. Check $VB_KEY — if set, you already have an API key. Skip straight to using the API.
2. Check $VB_PASSWORD — if set, you have a saved password. Log in to get a new API key.
3. If neither exists, sign up as a new user (see below).

Sign Up (new user)

POST /api/v1/auth
Body: { "email": "user@example.com", "password": "securepassword", "action": "signup" }
Response: { "key": "vb_live_abc123...", "keyId": "uuid", "userId": "user_...", "message": "Account created..." }

When signing up, auto-generate a secure password for the user. Immediately save both the API key and the password as environment variables so they persist across sessions:

export VB_KEY="vb_live_..."
export VB_PASSWORD="the-generated-password"

Log In (existing user)

If $VB_KEY is missing but $VB_PASSWORD is set, log in to get a fresh API key:

POST /api/v1/auth
Body: { "email": "user@example.com", "password": "$VB_PASSWORD" }
Response: { "key": "vb_live_abc123...", "keyId": "uuid", "userId": "user_...", "message": "Logged in..." }

Then save the new key: export VB_KEY="vb_live_..."

The API key is only shown once and cannot be retrieved later. Always save it immediately. Use it as Authorization: Bearer $VB_KEY for all other endpoints.

---

User Preferences

Store and retrieve the user's business context and content style. Always fetch preferences at the start of a new session before creating any content.

Get Preferences

GET /api/v1/preferences
Response: {
  "style": { "id": "uuid", "name": "Casual", "content": "8th grade reading level, lowercase, first-person POV..." } | null,
  "product_info": { "id": "uuid", "name": "My Business", "content": "We sell organic skincare products..." } | null
}

Save or Update a Preference

PUT /api/v1/preferences
Body: { "type": "style", "name": "My Style", "content": "casual tone, 8th grade reading level..." }
Body: { "type": "product_info", "name": "My Business", "content": "we sell X to Y audience..." }
Response: { "id": "uuid", "type": "style", "name": "...", "content": "..." }

Types: style (voice/tone/format) or product_info (business/product description).

Workflow:

1. On first session: GET /api/v1/preferences — if both are null, ask the user for their business description and content style, then save with PUT
2. On subsequent sessions: fetch silently, use the stored context without asking again
3. User can update preferences anytime by asking (e.g. "update my style to be more professional")

---

Content Ideation Process

Before creating a slideshow, always think through:

1. Hook — what makes someone stop scrolling? Lead with a bold claim, surprising fact, relatable pain point, or "you're doing X wrong" angle
2. Content — what does the audience actually need to hear? Use the stored product_info for business context
3. Voice — use the stored style preference for tone and format (reading level, POV, capitalization, etc.)
4. CTA — last slide should drive action: follow, save, comment, or visit

Do NOT ask the user to describe their business or style on every session if preferences are already stored.

---

Image Search

Search Unsplash

POST /api/v1/images/search
Body: { "query": "sunset beach", "per_page": 20, "page": 1, "color": "teal" }
Response: {
  "searchId": "uuid",
  "results": [{
    "index": 0,
    "id": "unsplash-id",
    "description": "A sunset over the ocean",
    "thumbnailUrl": "https://...",
    "url": "https://...",
    "photographer": "John Doe"
  }],
  "total": 500
}

Save searchId — needed for collection creation and the preview page URL.

color parameter (optional) — filter results by dominant color. Best values for dark slideshow backgrounds:

• teal — moody, atmospheric (works great for most topics)
• black — very dark, high drama
• blue — cool, calm, professional
• Omit for no filter (broadest results)

Results are automatically diversified across photographers — no two consecutive photos from the same person.

Image selection modes:

Auto mode (AI picks, no human review):

• Search with a color filter matching the content mood
• Use descriptions to reason about background suitability: prefer images described as landscapes, architecture, abstract, nature, or atmospheric scenes — avoid portraits, close-up faces, and busy text-heavy scenes
• Pick 8–12 images from across the result indices (not just the first few)

Preview mode (human picks):

• After searching, share the preview URL: https://viralbaby.co/preview/search/{searchId}
• Tell the user: "Here are the search results — tell me which numbers you want to use (e.g. '1, 3, 5, 8')"
• Wait for their response, then use those indices to create the collection

---

Collections

List Collections

GET /api/v1/collections
Response: [{ "id": "uuid", "name": "Beach Vibes", "imageCount": 12, "coverImageUrl": "..." }]

Create Empty Collection

POST /api/v1/collections
Body: { "name": "Beach Vibes", "description": "Sunset and ocean photos" }
Response: { "id": "uuid", "name": "Beach Vibes" }

Create Collection from Search Results

POST /api/v1/collections/from-search
Body: { "name": "Beach Vibes", "searchId": "uuid", "imageIndices": [0, 3, 5, 7] }
Response: { "collection": { "id": "uuid", "name": "Beach Vibes" }, "stats": { "total": 4, "successful": 4, "failed": 0 } }

This downloads the selected search result images to permanent storage. Maximum 30 images per request.

Get Collection Details

GET /api/v1/collections/{id}
Response: { "id": "uuid", "name": "...", "imageCount": 12, "images": [{ "id": "uuid", "url": "https://..." }] }

Delete Collection

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

---

Slideshows

List Slideshows

GET /api/v1/slideshows
GET /api/v1/slideshows?status=draft
Response: [{ "id": "uuid", "title": "...", "status": "draft", "slideCount": 5, "previewUrl": "https://viralbaby.co/preview/uuid" }]

Create Slideshow

Each slide is a background image with text overlays. Maximum 30 slides per slideshow.

Each slide can get its image from three sources (in priority order):

1. imageUrl — direct URL to any image
2. searchId + imageIndex — reference a previous search result by index
3. collectionId — random image from a collection

Text element options:

• text (required) — the text content
• type (required) — "title" (larger, bolder) or "subtitle" (smaller)
• fontSize (optional) — font size in px, defaults to 16 for title, 14 for subtitle
• textStyle (optional) — "stroke" (default, white text with black outline), "solid" (dark background), or "transparent" (shadow only)

POST /api/v1/slideshows
Body: {
  "title": "5 Morning Routine Tips",
  "aspectRatio": "3:4",
  "slides": [
    {
      "imageUrl": "https://example.com/photo.jpg",
      "textElements": [{ "text": "Your morning routine is broken", "type": "title" }]
    },
    {
      "searchId": "uuid",
      "imageIndex": 3,
      "textElements": [{ "text": "Here's why", "type": "title", "fontSize": 18 }]
    },
    {
      "collectionId": "uuid",
      "textElements": [
        { "text": "Tip #1: Wake up early", "type": "title" },
        { "text": "Even 30 minutes makes a difference", "type": "subtitle", "textStyle": "solid" }
      ]
    }
  ]
}
Response: {
  "id": "uuid",
  "title": "5 Morning Routine Tips",
  "previewUrl": "https://viralbaby.co/preview/uuid",
  "slides": [{ "id": "slide-...", "imageUrl": "...", "textElements": [...] }],
  "status": "draft"
}

Aspect ratios: 3:4 (default, best for TikTok), 1:1, 9:16, 4:5

Get Slideshow

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

Update Slideshow

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

Delete Slideshow

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

Render Slides (Server-Side)

Renders slides as JPEG images with text overlaid on background images. Returns S3 URLs.

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

---

AI Editing

Edit Slide with AI

Uses AI to modify a slide's text based on natural language instructions.

POST /api/v1/edit
Body: {
  "slideshowId": "uuid",
  "slideIndex": 0,
  "prompt": "make the hook more punchy and add a subtitle"
}
Response: {
  "updatedSlide": {
    "textElements": [
      { "text": "Stop doing this every morning", "type": "title", "fontSize": 16, "textStyle": "stroke" },
      { "text": "it's ruining your productivity", "type": "subtitle", "fontSize": 14, "textStyle": "stroke" }
    ]
  },
  "changes": { "description": "Rewrote hook to be more direct, added subtitle" }
}

The edit is auto-saved to the slideshow.

---

TikTok Integration

Connect TikTok Account

Returns a one-time OAuth URL. Open it in any browser — no dashboard login required.

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."
}

Give the authUrl to the user to open in their browser. They will complete TikTok's OAuth flow and see a success page when done. This only needs to be done once.

Check Connection Status

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

Upload to TikTok Drafts

Renders all slides server-side and uploads to the user's TikTok drafts (not published directly). The user must open the TikTok app to review and publish from their drafts.

POST /api/v1/tiktok/upload
Body: {
  "slideshowId": "uuid",
  "title": "5 Morning Routine Tips",
  "description": "Try these tips tomorrow morning",
  "hashtags": ["morningroutine", "productivity", "tips"]
}
Response: { "success": true, "publishId": "tiktok-publish-id", "renderedSlides": 5 }

• title — short title for the TikTok post
• description — caption text (up to 4000 characters, can be a longer detailed description)
• hashtags — array of up to 5 hashtags (with or without # prefix, auto-added). Appended to the description.

After a successful upload, tell the user: "Your slideshow has been uploaded to your TikTok drafts. Open the TikTok app to review and publish it."

---

Complete Workflow Example

Here's how to create and upload a slideshow end-to-end:

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": [0, 2, 5, 8, 11] }
   → 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 a slide with AI
   POST /api/v1/edit  { "slideshowId": "...", "slideIndex": 0, "prompt": "make the hook shorter and more shocking" }

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": "Try these tomorrow", "hashtags": ["morningroutine", "productivity"] }
   → Tell user to open TikTok app to review and publish from drafts

---

Error Responses

All errors follow this format:

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

Common status codes:

• 400 — Bad request (missing/invalid parameters)
• 401 — Invalid or missing API key
• 404 — Resource not found
• 500 — Server error