vibes-api

Unofficial Python API client for vibes.ai — Meta's AI video creation studio. Generate videos, images, TTS, lip-sync, and more, all from a Python script or CLI.

This package was built by reverse-engineering the vibes.ai Next.js bundles and observing real network traffic. It is not affiliated with, endorsed by, or officially supported by Meta or Vibes.

⚡ Quick start

# 1) Install
pip install VibesAI-api

# 2) Set your cookie (grab from DevTools → Application → Cookies → vibes.ai)
export VIBES_META_SESSION="e60e910a-242a-...-K54E"

# 3) Generate your first video
vibes-api one-shot \
  --prompt "A serene mountain landscape at sunset" \
  --aspect-ratio 16:9 --resolution 720p --variations 4 \
  --download-dir ./out

Or in Python:

from vibes_api import VibesClient, AspectRatio, Resolution

client = VibesClient(meta_session="...")
project = client.create_project(name="My Video")
batch = client.generate_video(
    project_id=project["id"],
    prompt="A serene mountain landscape at sunset",
    aspect_ratio=AspectRatio.LANDSCAPE,
    resolution=Resolution.P720,
    variations=4,
)
client.download_video(batch["content"][0]["id"], "sunset.mp4")

📦 What's inside

Core capabilities (v1.1.0)

Feature	Method	Notes
Auth	`get_me()`, `get_system_status()`, `logout()`	Cookie-based
Projects	`list_projects()`, `create_project()`, `get_project()`, `update_project()`, `delete_project()`, `duplicate_project()`
Video generation (t2v)	`generate_video()`	text-to-video, 1-4 variations
Image generation (t2i)	`generate_image()`	synchronous, returns immediately
🎥 Video extend (auto)	`auto_extend_video()`, `extend_video(prompt=None)`	extends a video by ~5s, no directive
🎥 Video extend (manual)	`manual_extend_video()`, `extend_video(prompt=...)`	extends with a directive prompt
🎥 Video edit (v2v)	`edit_video()`	re-render existing video with a directive
🎥 Image animate (auto)	`auto_animate_image()`	animate a still image with original prompt
🎥 Image animate (manual)	`manual_animate_image()`	animate with a directive prompt
🔄 Regenerate batch	`regenerate_batch()`	re-roll with same or new prompt
🖼️ Image editing	`edit_image()`	prompt-driven edits
✨ Prompt enhancement	`enhance_prompt()`	returns 4 AI-rewritten variations
🗣️ Lip sync	`generate_lipsync()`	image + audio + script → video
🔊 TTS	`tts()`, `list_voices()`, `save_tts_audio()`	41 preset voices
🎭 Start/end frame	`generate_video(start_frame=..., end_frame=...)`, `build_frame_handle()`	image-to-video with keyframes
🧙 Ingredients (character/style/scene)	`list_characters()`, `list_styles()`, `list_scenes()`, `create_ingredient()`, `delete_ingredient()`	studio ingredient CRUD
🧙 Ingredient refs in generation	`ingredients=[...]`, `create_ingredients=[...]`	apply or inline-create
🎨 Moodboards	`list_moodboards()`, `get_moodboard()`, `create_moodboard()`, `delete_moodboard()`
⬆️ Uploads	`upload_image()`, `upload_image_file()`, `upload_video_direct()`, `upload_audio_direct()`, `upload_media()`, `upload_profile_picture()`
📚 Media library	`list_media()`, `favorite_content_item()`, `delete_content_item()`, `delete_content_items()`
⬇️ Download	`download_video()`, `download_image()`
🔗 Share links	`create_share_link()`, `list_share_links()`, `revoke_share_link()`
🎵 Music library	`search_music()`, `lookup_music_thumbnail()`, `clip_music()`, `clip_audio()`
💬 Timeline chat	`timeline_chat()`	streaming AI assistant (SSE)
🎬 Timeline export	`export_timeline()`, `export_timeline_async()`, `check_export_status()`, `cancel_export()`	render composition → MP4
🔄 Real-time sync	`get_sync_status()`, `stream_sync_updates()`, `stream_batch_updates()`	SSE for collaborative editing
📊 Quota	`get_quota_upsell()`
⚙️ Account settings	`delete_account()`, `delete_all_media()`, `remove_all_posts()`
🐛 Bug reports	`report_bug()`, `record_consent()`
🤝 Collaborators	`list_collaborators()`, `remove_collaborator()`
📦 Project assets	`list_project_assets()`, `add_project_asset()`, `import_project_assets()`, `list_available_assets()`	cross-project reuse
⏳ Batch polling	`poll_batch()`, `list_batches()`, `list_project_batches()`, `get_batch()`, `delete_batch()`
🚀 One-shot	`create_video_from_prompt()`	end-to-end convenience

CLI

The vibes-api CLI exposes every feature as a subcommand. Run vibes-api --help for the full list.

# User
vibes-api me

# Projects
vibes-api projects list
vibes-api projects create --name "My Video"
vibes-api projects get <id>
vibes-api projects delete <id> --delete-assets

# Video generation
vibes-api videos generate --project-id <id> --prompt "sunset over ocean" \
  --aspect-ratio 16:9 --resolution 720p --variations 4 --download-dir ./out

# 🆕 Video extend (auto/manual)
vibes-api videos extend --project-id <id> --batch-id <batch> \
  --content-id <content>  # auto-extend (no --prompt)
vibes-api videos extend --project-id <id> --batch-id <batch> \
  --prompt "camera pans up to reveal the sky"  # manual extend

# 🆕 Video edit (v2v)
vibes-api videos edit --project-id <id> --batch-id <batch> \
  --prompt "change the weather to rain"

# Image generation
vibes-api images generate --project-id <id> --prompt "cyberpunk city"

# 🆕 Image animate (auto/manual)
vibes-api images animate --project-id <id> --content-id <content>
vibes-api images animate --project-id <id> --content-id <content> \
  --prompt "camera zooms in slowly"

# 🆕 Batch regenerate (re-roll)
vibes-api batches regenerate <batch-id> --project-id <id>
vibes-api batches regenerate <batch-id> --project-id <id> --prompt "new prompt"

# 🆕 Ingredient CRUD
vibes-api ingredients list [--type CHARACTER|STYLE|SETTING]
vibes-api ingredients create --name "My Character" --type CHARACTER \
  --image-ent-id <id> --image-url <url>
vibes-api ingredients delete <ingredient_id>

# TTS
vibes-api voices list
vibes-api tts --voice play_ai_Marisol --text "Hello world" --out hello.mp3

# Media library
vibes-api media list --type video --limit 10
vibes-api media download --id <id> --out video.mp4
vibes-api media delete --ids <id1> <id2>

# Prompt enhancement
vibes-api prompts enhance --prompt "a cat"

# Share links
vibes-api share create --entity-type project --entity-id <id>
vibes-api share list --entity-type project --entity-id <id>
vibes-api share revoke <share_link_id>

# Batches
vibes-api batches list --project-id <id>
vibes-api batches get <batch_id>
vibes-api batches poll <batch_id> --timeout 180

# Music
vibes-api music search --query "lofi"

# Timeline AI chat
vibes-api chat "add a 5 second sunset clip"

# 🆕 Real-time sync
vibes-api sync status --entity-type project --entity-id <id>
vibes-api sync stream --entity-type project --entity-id <id>  # Ctrl+C to stop

# 🆕 Quota
vibes-api quota

# End-to-end one-shot
vibes-api one-shot --prompt "sunset over ocean" --download-dir ./out

🎬 Generation flow (under the hood)

Vibes uses a two-step generation pattern:

1) POST /api/generation-batches    → create a batch shell (with client-generated UUID v7)
2) POST /api/generate/videos       → trigger actual generation
3) GET  /api/generation-batches/{id} → poll until isComplete=true
                                     OR  /api/generation-batches/{id}/stream (SSE)

The client abstracts this away behind generate_video() (which polls by default) and generate_image() (which is synchronous).

Batch IDs are UUID v7 with `batch-` prefix

The server expects batch IDs to be UUID v7 (timestamp-ordered) prefixed with batch- so it can derive the creation time from the high bits AND so that the download endpoint accepts the content IDs. The client generates these internally via _uuid_v7(). Special flows use different prefixes:

batch-<uuid_v7> — normal text/image generation
extend-<timestamp>-<random> — video extension
image2video-<timestamp>-<random> — image-to-video (animate)
video2video-<timestamp>-<random> — video-to-video (edit)

Aspect ratios & resolutions

Only 3 aspect ratios are supported (verified live):

Aspect	Image dimensions	Notes
`1:1`	1280×1280	Square
`9:16`	720×1280	Portrait (UI default)
`16:9`	1280×720	Landscape

Resolutions: 480p (default, faster) and 720p (slower but higher quality).

Models

Type	Default model	Description
Image	`midjen-base`	Standard image generation
Video (t2v / i2v)	`midjen-short`	~5 second clips
Video extend	`midjen-extend`	For extending an existing video
Video edit (v2v)	`midjen-video-edit`	For re-rendering with a directive
Lip sync	`lipsync` / `midjen-lipsync-async`	Lip-sync generation
Prompt LLM	`gemini-2.5-flash`	Used for prompt enhancement

Generation types

`generationType`	When to use
`t2v`	text → video
`t2i`	text → image
`i2v`	image (start frame) → video
`extend`	extend an existing video
`v2v`	video → video (re-render with directive)
`lipsync`	lip-sync generation

🎭 Ingredients (characters, styles, scenes)

Vibes supports three ingredient types:

CHARACTER (UI: "Character") — applies via orefImageHandle internally
STYLE (UI: "Style") — applies via srefImageHandle internally
SETTING (UI: "Scene") — applies via settingImageHandles internally

There are three ways to reference an ingredient in a generation:

from vibes_api import IngredientType
from vibes_api.ingredients import IngredientRef, CreateIngredient

# 1. By existing ingredient ID (from list_ingredients)
character = IngredientRef.by_id(
    ingredient_id="800957099700717",
    ingredient_type=IngredientType.CHARACTER,
    name="Valdrin",
    image_url="https://...",
)

# 2. By uploaded image entity ID (creates a new ingredient on-the-fly)
style = CreateIngredient.by_image_ent_id(
    image_ent_id="1177...",
    ingredient_type=IngredientType.STYLE,
    name="Cyberpunk neon",
    image_url="https://...",
)

# 3. By name only (uses prompt-generated image)
scene = CreateIngredient.by_name(
    ingredient_type=IngredientType.SETTING,
    name="Misty forest at dawn",
)

# Pass them to generate_video
batch = client.generate_video(
    project_id=project["id"],
    prompt="...",
    ingredients=[character],            # goes in `ingredients[]`
    create_ingredients=[style, scene],  # goes in `createIngredients[]`
)

You can also CRUD ingredients directly:

client.list_characters(), list_styles(), list_scenes()
client.create_ingredient(name, ingredient_type, source_image_ent_id, ...)
client.delete_ingredient(ingredient_id)

🖼️ Start/end frame (image-to-video with keyframes)

Generate a video that interpolates between two keyframes:

# Generate the start frame image
start_resp = client.generate_image(
    project_id=project["id"],
    prompt="a rose in full bloom",
    aspect_ratio="16:9",
)
# Generate the end frame image
end_resp = client.generate_image(
    project_id=project["id"],
    prompt="a withered, dried rose",
    aspect_ratio="16:9",
)

# Build frame handles
start_frame = client.build_frame_handle({
    "mediaEntId": start_resp["data"][0]["imageEntId"],
    "imageUrl": start_resp["data"][0]["url"],
})
end_frame = client.build_frame_handle({
    "mediaEntId": end_resp["data"][0]["imageEntId"],
    "imageUrl": end_resp["data"][0]["url"],
})

# Generate the video with both keyframes
batch = client.generate_video(
    project_id=project["id"],
    prompt="the rose slowly wilts, time-lapse effect",
    start_frame=start_frame,
    end_frame=end_frame,
    aspect_ratio="16:9",
)

For a single start frame (i2v without end frame), just omit end_frame.

🎥 Video extend (auto + manual)

The Vibes UI shows "Auto extend" and "Manual extend" buttons next to each generated video. Both call the same backend — the only difference is whether you supply a directive prompt:

# Get a previously-generated video's full content item
batch = client.get_batch("batch-...")
source_video = batch["content"][0]

# AUTO extend: no prompt, server continues original
extended_auto = client.extend_video(
    project_id=project["id"],
    source_video=source_video,
)

# MANUAL extend: provide a directive
extended_manual = client.manual_extend_video(
    project_id=project["id"],
    source_video=source_video,
    prompt="camera pans up to reveal the sky",
)

The source_video dict must be the full content item (not just an ID) because extend needs the original videoHandle, videoGenEntId, and structuredOutput from the source.

🔑 Authentication

Vibes uses a single cookie, meta_session, for authentication. The cookie value is a UUID session token.

How to get your cookie

Log in at vibes.ai in your browser (currently requires a Meta/Facebook account).
Open DevTools (F12) → Application → Cookies → https://vibes.ai.
Copy the value of meta_session (a long string with a UUID format like e60e910a-...-K54E).

Pass it to the client:

client = VibesClient(meta_session="e60e910a-...")

Or via env var:

export VIBES_META_SESSION="e60e910a-..."

Cookie rotation

Cookies expire. The web app refreshes them silently via /api/auth/me. When you start getting 401 Unauthorized errors, grab a fresh cookie from the browser and create a new VibesClient. You said you'll rotate them — this is the only manual step.

TTS-specific limitation

The TTS endpoint (/api/studio/playai/tts) depends on a server-side Facebook access token that rotates independently of your meta_session. If you see 403 Facebook expired access token, just wait a few minutes and retry. The Vibes backend auto-refreshes this token on its own schedule.

📡 API endpoint reference

All endpoints are under https://vibes.ai/api/. This list was extracted directly from the Next.js JS bundles.

Auth & system

GET /api/auth/me — current user
POST /api/auth/logout — invalidate session
POST /api/auth/check-token — token validation
GET /api/system-status — system status banner
POST /api/analytics — usage analytics (fire-and-forget)
POST /api/bug-report — bug reporting
POST /api/consent/record — cookie consent
GET /api/quota/upsell — upsell info

Projects

GET /api/projects — list (params: limit, offset, sort, search)
POST /api/projects — create
GET /api/projects/{id} — get
PUT /api/projects/{id} — update name/composition
DELETE /api/projects/{id}?deleteAssets=true — delete
POST /api/projects/{id}/duplicate — duplicate
POST /api/projects/{id}/upload — bulk upload media
GET /api/projects/{id}/batches?limit=6&offset=0 — list batches in project
GET /api/projects/{id}/assets — list project assets
POST /api/projects/{id}/assets — add asset
POST /api/projects/{id}/assets/import — import from another project
GET /api/projects/{id}/assets/available?sourceProjectId={id} — list importable
POST /api/projects/{id}/timeline/download — sync export to MP4
POST /api/projects/{id}/timeline/export-surfguard — start async export
GET /api/projects/{id}/timeline/export/{exportId}/status — poll export
POST /api/projects/{id}/timeline/export/{exportId}/cancel — cancel

Generation batches

GET /api/generation-batches?limit=12&offset=0 — list (optional projectId, type)
POST /api/generation-batches — create (body must include client-generated UUID v7 as id)
GET /api/generation-batches/{id} — get full state
PUT /api/generation-batches/{id} — update
DELETE /api/generation-batches/{id} — delete
GET /api/generation-batches/{id}/stream — SSE stream of batch updates

Generation

POST /api/generate/videos — text-to-video, image-to-video, extend, v2v edit, image animate (all via different type and config values)
POST /api/generate/images — text-to-image (synchronous)
POST /api/generate/image-edit — edit an existing image
POST /api/generate/prompts — prompt enhancement (returns 4 variations)
POST /api/animate/generate — lip sync / animation

Studio

GET /api/studio/ingredients?ownerFilter=LIBRARY|VIEWER&ingredientType=... — list ingredients
POST /api/studio/ingredients — create ingredient
DELETE /api/studio/ingredients/{id} — delete ingredient
GET /api/studio/voices — list TTS voices
POST /api/studio/playai/tts — text-to-speech (body: {text, voice, outputFormat, language?})

Uploads

POST /api/upload-image — base64 image upload (body: {image: "<base64>"})
POST /api/upload-media — multipart form (file + filename)
POST /api/upload-video-direct — multipart form (video)
POST /api/upload-audio-direct — multipart form (audio)
POST /api/upload-profile-picture — profile picture

Media library & content items

GET /api/media-library?limit=50&offset=0&type=&sort=&search= — list
GET /api/download/video?id={contentItemId} — download video MP4
GET /api/download/png?id={contentItemId} — download image PNG
GET /api/download/{type}?id={id} — generic download
POST /api/content-items/{id}/favorite — toggle favorite
POST /api/content-items/{id}/retry — retry failed item
POST /api/content-items/{id}/feedback — submit feedback
DELETE /api/content-items/{id} — delete one
POST /api/content-items/bulk-delete — bulk delete (body: {ids: [...]})

Audio / music

GET /api/meta-music?q=&limit=&cursor= — search Meta music library
GET /api/meta-music/lookup?id=&title= — resolve track thumbnail
POST /api/meta-music/oa-check — check original audio status
POST /api/media/music/clip — clip a music track segment
POST /api/media/audio/clip — clip any audio URL
GET /api/proxy-audio — proxy audio through Vibes CDN
GET /api/resolve-audio-urls — resolve audio CDN URLs

Moodboards & playables

GET /api/moodboards — list
POST /api/moodboards — create
GET /api/moodboards/{id} — get
DELETE /api/moodboards/{id} — delete
GET /api/playables — list playables (currently disabled: "Playables not enabled")

Timeline AI

POST /api/timeline/chat/stream — streaming SSE chat (body: {input, instructions, tools?, composition?})
- Event types: message_delta, message_done, tool_call, tool_response, reasoning_delta, reasoning_done, completed, error
- Default tools (sent by the client): generate_image, generate_video, add_music, add_text_overlay, update_text_overlay, resize_clip, move_clip, extend_timeline_to, delete_clip, delete_track, split_clip, duplicate_clip, set_fade, set_volume, set_speed, mute_track, rename_track, reorder_clips, generate_lipsync, create_ingredient_from_clip

Share & collaborators

POST /api/share-links — create (body: {entityType, entityId, expiresAt?, maxUses?})
GET /api/share-links?entityType=&entityId= — list
DELETE /api/share-links/{id} — revoke
GET /api/collaborators?entityType=&entityId= — list
DELETE /api/collaborators/{id} — remove

🆕 Real-time sync (SSE)

GET /api/sync?entityType=&entityId= — get last-updated timestamp
GET /api/sync/stream?entityType=&entityId= — SSE stream of update events (snapshot, update, bye)

Settings

POST /api/settings/delete-account
POST /api/settings/delete-all-media
POST /api/settings/remove-all-posts

Meta integration

POST /api/meta-graphql — Meta GraphQL proxy (body: {doc_id, variables})
POST /api/meta-oidc/start — start OIDC flow
POST /api/meta-profiles/publish — publish profile
POST /api/revisions — session revisions

🧪 Examples

Ten ready-to-run example scripts in examples/:

01_generate_video.py — end-to-end video generation
02_images_and_edits.py — image generation + editing + media library
03_tts_and_lipsync.py — TTS → upload → lip sync pipeline
04_prompts_and_chat.py — prompt enhancement + timeline AI chat
05_ingredients.py — using saved characters in generations
06_extend_video.py — 🆕 auto-extend and manual-extend a video
07_ingredients_full.py — 🆕 character + style + scene combos
08_create_ingredient.py — 🆕 create a new ingredient via API
09_start_end_frame.py — 🆕 image-to-video with keyframe interpolation
10_edit_video.py — 🆕 video-to-video editing (re-render with directive)

Run any of them with:

export VIBES_META_SESSION="..."
python /home/z/my-project/download/vibes-api/examples/01_generate_video.py

⚠️ Limitations & caveats

Cookie rotation — meta_session expires. Re-grab from the browser when 401s appear.
TTS backend token — /api/studio/playai/tts depends on a server-side FB token that rotates independently. If you get 403 Facebook expired access token, wait and retry.
Generation quotas — Vibes enforces per-user quotas (visible in the UI). Hit it and you'll get 429 or a GENERATION_FAILED with quota detail.
No public API — All endpoints here are private and could change at any time. Pin to a client version if stability matters.
Content IDs for download — download_video(id) expects the format batch-{uuid}-content-{n}. The client uses the batch- prefix consistently so this works for client-generated batches.
Rate limiting — Don't hammer the API. The client uses a single requests.Session; if you need parallelism, instantiate multiple clients and rotate cookies.
Aspect ratios — Only 1:1, 9:16, 16:9 are supported (server-enforced). Other values return GENERATION_FAILED.
Video extend requires full content item — extend_video(source_video=...) needs the full content item dict (from get_batch()), not just an ID. The client extracts videoHandle, videoGenEntId, and structuredOutput from it.
v2v edit may fail on old videos — edit_video() requires videoHandle metadata which older videos may not have. You'll get a clear error message in that case.
Sentry analytics — The web app posts to Sentry for error tracking. This client does not replicate that (it's noise for API use).

🛠️ Development

# Install in editable mode
pip install VibesAI-api

# Run tests (requires VIBES_META_SESSION env var)
pytest

# Build CLI
python -m vibes_api.cli --help

Project layout

vibes-api/
├── pyproject.toml
├── README.md
├── QUICKREF.md
├── TEST_RESULTS.md
├── vibes_api/
│   ├── __init__.py       # Public API surface
│   ├── client.py         # VibesClient main implementation (~2400 lines, 87 methods)
│   ├── cli.py            # Argparse-based CLI
│   ├── models.py         # Enums: AspectRatio, Resolution, VideoModel, etc.
│   └── ingredients.py    # Ingredient payload builders
├── examples/
│   ├── 01_generate_video.py
│   ├── 02_images_and_edits.py
│   ├── 03_tts_and_lipsync.py
│   ├── 04_prompts_and_chat.py
│   ├── 05_ingredients.py
│   ├── 06_extend_video.py        # 🆕
│   ├── 07_ingredients_full.py    # 🆕
│   ├── 08_create_ingredient.py   # 🆕
│   ├── 09_start_end_frame.py     # 🆕
│   └── 10_edit_video.py          # 🆕
└── research/
    └── ... (reversing notes, sample responses, screenshots)

📜 License

MIT. This project is not affiliated with Meta or Vibes. Use at your own risk; respect Vibes' Terms of Service.

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
examples		examples
research		research
server		server
tests		tests
vibes_api		vibes_api
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile		Dockerfile
FEATURE_MATRIX.md		FEATURE_MATRIX.md
LICENSE		LICENSE
QUICKREF.md		QUICKREF.md
README.md		README.md
TEST_RESULTS.md		TEST_RESULTS.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
requirements-server.txt		requirements-server.txt

Folders and files

Latest commit

History

Repository files navigation