v1.0 Stable

Swipee API

Programmatically generate AI-powered carousels, export images, and integrate with your workflow.

Generate

AI content from any topic

Export

PNG, PDF, or ZIP bundle

Video

Animated for Reels/TikTok

Base URL

https://swipee.io/api

Authentication

Authenticate requests using your API key. You can find your API keys in your account settings.

Option 1: Authorization Header

bash

curl https://swipee.io/api/generate \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"topic": "productivity tips"}'

Option 2: X-API-Key Header

bash

curl https://swipee.io/api/generate \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"topic": "productivity tips"}'

Security: Keep your API key secret. Never expose it in client-side code or public repositories.

Rate Limits

Limits are based on your subscription plan. Exceeding limits returns a 429 status code.

Plan	Monthly Limit	Price
Free	3 carousels	$0
Pro	30 carousels	$9/mo
Unlimited	Unlimited	$19/mo

Recommended

POST/api/generate-images

Generate Carousel Images

End-to-end carousel generation. Send a topic, receive ready-to-post PNG images. No client-side rendering required.

Parameters

topicstringrequired

The topic or prompt for carousel generation

slideCountinteger

Number of slides. Default: 5, Range: 3-10

languagestring

Content language (en, es, fr, de, etc.). Default: en

themestring

Visual theme. Default: gradientPurple

aspectRatiostring

1:1, 4:5, 9:16, 16:9. Default: 4:5

widthinteger

Output width in pixels. Default: 1080

handlestring

Social handle for branding (@username)

showWatermarkboolean

Add watermark. Default: false

outputstring

zip (download) or json (base64). Default: zip

Example: Download ZIP

bash

curl -X POST https://swipee.io/api/generate-images \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "5 productivity tips for developers",
    "theme": "gradientPurple",
    "aspectRatio": "4:5",
    "handle": "@yourhandle"
  }' --output carousel.zip

Example: Get Base64

bash

curl -X POST https://swipee.io/api/generate-images \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Morning routine tips",
    "output": "json"
  }'

JSON Response (output=json)

json

{
  "slides": [...],
  "images": [
    {
      "index": 1,
      "filename": "slide-01.png",
      "base64": "iVBORw0KGgo...",
      "dataUrl": "data:image/png;base64,iVBORw0KGgo..."
    }
  ],
  "meta": {
    "slideCount": 5,
    "theme": "gradientPurple",
    "aspectRatio": "4:5"
  }
}

Response Codes

200Images generated successfully

400Invalid request parameters

401Invalid or missing API key

429Rate limit exceeded

POST/api/generate

Generate Carousel JSON

Generate carousel content as JSON data. Use this if you want to render slides yourself or need the raw content.

Parameters

topicstringrequired

The topic or prompt for carousel generation

slideCountinteger

Number of slides to generate. Default: 5, Range: 3-10

languagestring

Content language code (en, es, fr, de, etc.). Default: en

templateIdstring

Content template ID. See Templates section

tonestring

Content tone: educational, casual, or professional

includeImagesboolean

Include image search suggestions in response

Example Request

bash

curl -X POST https://swipee.io/api/generate \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "5 JavaScript tips for beginners",
    "slideCount": 5,
    "tone": "educational"
  }'

Response

json

{
  "slides": [
    {
      "title": "5 JS Tips You Need",
      "content": "Level up your JavaScript skills with these essential tips",
      "code": null
    },
    {
      "title": "1. Use Optional Chaining",
      "content": "Safely access nested properties without errors",
      "code": "const name = user?.profile?.name ?? 'Guest';",
      "language": "javascript",
      "filename": "example.js"
    }
  ],
  "meta": {
    "isCodeTopic": true,
    "slideCount": 5
  }
}

Response Codes

200Content generated successfully

400Invalid request parameters

401Invalid or missing API key

429Rate limit exceeded

POST/api/export

Export Carousel

Render carousel slides as downloadable images (PNG/ZIP) or video. Requires server-side rendering setup.

Parameters

slidesarrayrequired

Array of slide objects (from /generate response)

formatstringrequired

Export format: png, zip, or video

themestring

Theme ID. Default: gradientPurple

aspectRatiostring

Output ratio: 1:1, 4:5, 9:16, 16:9. Default: 4:5

widthinteger

Output width in pixels. Default: 1080

handlestring

Social handle for branding (e.g., @username)

Format Options

png

Single slide image

zip

All slides as archive

video

Animated MP4

Example

bash

curl -X POST https://swipee.io/api/export \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "slides": [...],
    "format": "zip",
    "theme": "gradientBlue",
    "aspectRatio": "4:5"
  }' --output carousel.zip

GET/api/images

Search Images

Search royalty-free stock images from Pexels for use in your carousels.

Query Parameters

querystringrequired

Search query for images

perPageinteger

Results per page. Default: 12, Max: 80

pageinteger

Page number for pagination. Default: 1

orientationstring

Filter: landscape, portrait, or square

Example

bash

curl "https://swipee.io/api/images?query=productivity&perPage=5" \
  -H "Authorization: Bearer sk_your_api_key"

POST/api/import-url

Import from URL

Extract content from any URL (blog posts, articles) and convert it into carousel-ready data.

Parameters

urlstringrequired

URL of the content to import

Example

bash

curl -X POST https://swipee.io/api/import-url \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://blog.example.com/article"}'

POST/api/import-twitter

Import from Twitter/X

Convert a tweet or thread into carousel content.

Parameters

urlstringrequired

Twitter/X post URL

Example

bash

curl -X POST https://swipee.io/api/import-twitter \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://x.com/user/status/123456789"}'

Content Templates

Use the templateId parameter to structure content in proven formats.

Template ID	Description
quotes-motivational	Motivational quotes
tips-quick	Quick tips format
tips-mistakes	Common mistakes to avoid
howto-steps	Step-by-step guide
listicle-top	Top X list format
comparison-vs	This vs That comparison
comparison-myths	Myths vs Facts
story-transformation	Before/After transformation
educational-explainer	Concept explainer
educational-checklist	Checklist format

Error Handling

All errors return standard HTTP status codes with a JSON body containing error details.

Code	Description
200	Success
400	Bad request — Invalid or missing parameters
401	Unauthorized — Invalid or missing API key
429	Rate limited — Too many requests
500	Server error — Something went wrong

Error Response Format

json

{
  "error": "Topic is required",
  "code": "missing_parameter"
}

Need help? Contact us at support@swipee.io