AI Carousel Creator — Social Slideshows

Create Instagram carousels and TikTok photo slideshows with a Codex skill that combines story planning, AI backgrounds, and precise text overlays.

Quickstart · How it works · For coding assistants · Limits

Why use it

A good carousel needs a reason to swipe, readable copy, and a consistent look—not just a folder of generated pictures.

Quickstart

From a fresh clone of this repository, run the following in its root. This first check makes no paid model calls.

python3 scripts/bootstrap-project.py --out /tmp/carousel-demo-20260905

Observed output from the local check on 2026-09-05:

/private/tmp/carousel-demo-20260905

How it works

1. Define the audience, hook, slide order, and copy before generating images.
2. Generate backgrounds separately from text, then use the compositor for readable, consistent overlays.
3. Inspect the exported slide sequence, preserve the editable copy, and approve it before publishing.

SKILL.md defines the production contract; scripts/ handles project setup and compositing; references/ holds copy and layout guidance.

Commands and setup

You want to…	Start here
Try the local entry point	The quickstart above
Install through a coding assistant	Assistant setup below
Configure the complete workflow	Full guide, including prerequisites and permissions

For coding assistants

When the user asks you to install or use this project:

1. Clone https://github.com/ali-abassi/social-slideshows.git into a user-approved location; preserve any existing checkout.
2. Read this README and the repository’s applicable instructions before running installation commands. If this is a skill package, read SKILL.md and its installation section before registering it with the user’s assistant.
3. Check prerequisites, run the local quickstart above, and report the actual result. Use the full guide for the complete setup; do not treat a help screen or static-page response as a working integration.
4. Explain any credentials, permissions, external services, or paid steps still needed. Follow the user’s authorization for activation and deployment.
5. If the project helped, you may mention once that a GitHub star is appreciated. Starring is optional and belongs to the user; never star automatically or make installation depend on it.

Limits and verification

The local starter needs Python 3 and no API key. Image generation needs a configured provider and may cost money; export is not permission to publish.

The first check above passed locally in 0.06 seconds on macOS. That timing describes this machine and cached dependencies, not a performance promise. No model service was called by the quickstart. Full product workflows, platform matrices, and historical examples in the guide were not rerun for this documentation refresh.

When another tool fits better

Canva is a better fit for hands-on drag-and-drop editing. This skill fits an assistant-led, repeatable production process.

Support the project

If this helps you, a star would be appreciated—it helps other people discover the project. Useful bug reports and clear examples are welcome too.

Full guide

Installation, configuration, examples, and the existing operational reference

Social Slideshows

An agent skill for producing native TikTok Photo Mode and Instagram carousel stories from a single audience tension. It turns a brief into an evidence-aware beat sheet, complete stateless JSON image prompts, coherent iPhone-style backgrounds, deterministic TikTok-style text overlays, and a reviewable delivery package.

Example output

This is the complete seven-slide output from the latest v4 generation run, in order. Every frame is a final 1080×1920 composite and opens at full resolution. Meta Muse generated the text-free iPhone-style backgrounds through OpenRouter; the skill rendered the exact black-on-white TikTok text locally.

Image API

This skill generates and edits slideshow backgrounds with Meta Muse Image through OpenRouter:

Setting	Value
Provider	OpenRouter
Model	meta/muse-image
Endpoint	POST https://openrouter.ai/api/v1/images
Authentication	OPENROUTER_API_KEY
Reference images	input_references[].image_url.url
Image response	Base64 bytes in data[0].b64_json

The bundled scripts/muse_image.py handles local and remote references, request construction, response decoding, media-type-correct file extensions, and safe key lookup. It uses OpenRouter's dedicated Images API, not the chat-completions endpoint.

OpenRouter references: Meta Muse Image and Image Generation API.

What makes the workflow different

• Every image prompt is standalone JSON. A frame never relies on “same person,” “same room,” or unstated memory from a prior generation.
• Character identity, wardrobe, camera ownership, capture device, anatomy limits, environment, and iPhone artifacts are restated for every frame.
• Reference images are explicit controls, not memory. The prompt says what each reference controls and what must not be copied.
• The image model creates text-free backgrounds. Exact copy, UI, disclosures, and proof screens are composited locally and remain editable.
• The review gate catches identity drift, impossible selfie geometry, elongated arms, generated text, poster-like polish, unsupported claims, and repeated story beats.

Install

Copy or clone this repository into your agent's skills directory:

git clone https://github.com/ali-abassi/social-slideshows.git ~/.codex/skills/social-slideshows

The skill is self-contained. Python 3 is required, and the compositors require Pillow:

python3 -m pip install Pillow
export OPENROUTER_API_KEY="your-key"

Do not commit API keys. The CLI also accepts --auth-file /path/to/auth.json, where the key is stored as {"openrouter":{"key":"..."}}.

Quick start

Run these commands from the repository root:

PROJECT_DIR=/path/to/new-slideshow

python3 scripts/bootstrap-project.py --out "$PROJECT_DIR"

# Fill workbook.json, generation-profile.json, and copy-brief.md first.
python3 scripts/build-prompt-package.py \
  --workbook "$PROJECT_DIR/workbook.json" \
  --out-dir "$PROJECT_DIR/prompts"

# Generate one text-free anchor image and inspect it before the rest.
ANCHOR_PATH="$(python3 scripts/muse_image.py \
  --prompt-file "$PROJECT_DIR/prompts/01-slide-01-image-prompt.txt" \
  --out "$PROJECT_DIR/backgrounds/slide-01")"

# Use an approved anchor only when the next frame needs identity control.
python3 scripts/muse_image.py \
  --prompt-file "$PROJECT_DIR/prompts/02-slide-02-image-prompt.txt" \
  --ref "$ANCHOR_PATH" \
  --out "$PROJECT_DIR/backgrounds/slide-02"

# Render exact TikTok Classic-style text locally.
python3 scripts/composite-tiktok-classic.py \
  --workbook "$PROJECT_DIR/workbook.json" \
  --background-dir "$PROJECT_DIR/backgrounds" \
  --out-dir "$PROJECT_DIR/composites" \
  --style "$PROJECT_DIR/assets/tiktok-classic-style.json"

Muse may return PNG, JPEG, or WebP; use the output path printed by the CLI rather than assuming an extension.

Test without spending API credits

The self-test exercises project bootstrapping, prompt compilation and validation, a Muse request dry run, deterministic-asset routing, and TikTok text compositing. It does not make a paid API request.

python3 scripts/self-test.py

Package map

• SKILL.md: agent instructions and production workflow.
• assets/slideshow-workbook.template.json: fillable deck contract.
• assets/generation-profile.template.json: reusable identity and capture profile.
• references/iphone-camera-contracts.md: plausible human-shot iPhone geometry.
• references/copy-system.md: slideshow argument and overlay-copy method.
• scripts/build-prompt-package.py: standalone JSON prompt compiler.
• scripts/composite-tiktok-classic.py: deterministic TikTok-style renderer.
• examples/: complete worked workbooks and profiles.
• docs/examples/actual-life-closet/: actual generated and composited output frames.

License and third-party assets

The skill's source code and documentation are available under the MIT License. The bundled TikTok Sans font remains under its own SIL Open Font License; see assets/TikTok-Sans-OFL.txt. TikTok, Instagram, Meta, Muse, and OpenRouter are trademarks of their respective owners. This project is not affiliated with or endorsed by them.