Brainrotify

REST

JSON

API Reference

Programmatic access to the full Brainrotify engine. Generate brainrot videos, AI songs, and animated clips with the same pipeline powering the app.

Base URL

https://www.brainrotify.me/api/v1

Auth

X-API-Key: brk_…

Quickstart

Three shell commands to a rendered video.

KEY="brk_YOUR_KEY_HERE" # Submit a render job RESP=$(curl -s -X POST https://www.brainrotify.me/api/v1/render \ -H "X-API-Key: $KEY" -H "Content-Type: application/json" \ -d '{ "movie": { "mode": "brainrot", "title": "Black holes", "scenes": [{ "narration": "Black holes bend space and time itself.", "media": [{ "kind": "web_image", "search_query": "black hole" }] }] }, "settings": { "background_video_url": "https://cdn.brainrotify.me/assets/background_videos/minecraft-parkour-1_clip.mp4", "narrator_voice_id": "default", "subtitle_font": "Impact", "words_per_subtitle": 1 }, "variables": {} }') JOB_ID=$(echo $RESP | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])") # Poll until done while true; do R=$(curl -s https://www.brainrotify.me/api/v1/render/$JOB_ID -H "X-API-Key: $KEY") echo $R STATUS=$(echo $R | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])") [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break sleep 5 done

Authentication

Every request needs an X-API-Key header. Keys start with brk_. Create and manage keys in your Dashboard → API Keys. Your first key gets 10 free trial API credits.

curl https://www.brainrotify.me/api/v1/credits/balance \ -H "X-API-Key: brk_YOUR_KEY"

Error codes

Code

Meaning

401

Missing / invalid / revoked key

402

Insufficient API credits — detail shows cost + balance

403

Key has no API access — subscribe to an API plan

404

Resource or job not found

429

Rate limit exceeded — back off Retry-After seconds

Rate limits per key: free 5 rpm · starter 30 · growth 90 · scale 300

Catalog (read-only)

All accept ?search=, ?limit= (≤ 200), ?offset=. Returns {"data":[…],"count":N,"offset":N}.

GET

https://www.brainrotify.me/api/v1/characters

List avatar/voice characters

GET

https://www.brainrotify.me/api/v1/characters/{id}

Get one character

GET

https://www.brainrotify.me/api/v1/voices

List TTS / RVC voices

GET

https://www.brainrotify.me/api/v1/voices/{id}/preview

302 → preview audio

GET

https://www.brainrotify.me/api/v1/backgrounds

List background videos

GET

https://www.brainrotify.me/api/v1/backgrounds/categories

Category map

GET

https://www.brainrotify.me/api/v1/music

List background music

GET

https://www.brainrotify.me/api/v1/music/{id}

One track

GET

https://www.brainrotify.me/api/v1/music/{id}/preview

302 → preview clip

GET

https://www.brainrotify.me/api/v1/music/categories

Genre / mood map

Videos — scene pipeline

Full per-scene control. You supply the scenes + media elements. For AI-written scripts use POST /videos/classic below.

POST

https://www.brainrotify.me/api/v1/videos/generate

Submit → 202 {job_id, status, credits_used}

GET

https://www.brainrotify.me/api/v1/videos/{job_id}

Poll → {status, video_url, error}

GET

https://www.brainrotify.me/api/v1/videos

List your video jobs

POST /videos/generate body

{ "mode": "brainrot", "title": "3 facts about black holes", "background_video_id": "minecraft-parkour-1", "voice_settings": { "voice_id": "narrator_default" }, "caption_settings": { "font": "Impact", "words_per_subtitle": 1 }, "scenes": [ { "narration": "Black holes bend time itself.", "media": [{ "kind": "web_image", "search_query": "black hole" }] } ], "webhook_url": "https://you.example.com/hooks/brainrotify" }

Field

Type

Notes

mode

string

brainrot · story · story_reddit · story_messages · quiz · conversation · avatar · avatar_multi

background_video_id

string

From GET /backgrounds

scenes[].media[].kind

string

ai_image · web_image · web_gif

scenes[].media[].x/y/w/h

float?

Normalized 0–1 coords on the canvas. Omit → auto

scenes[].audio[]

array?

{url, volume, start_sec, loop} — per-scene SFX

webhook_url

string?

POSTed with final status on completion

Videos — classic / script pipeline

The LLM writes the entire narration script from your topic. Supports story, Reddit post, iMessage, and quiz formats. Best when you don't want to write scenes manually. Poll the result at GET /videos/{job_id}.

POST

https://www.brainrotify.me/api/v1/videos/classic

Submit → 202 {job_id, status, credits_used}

POST /videos/classic body

{ "mode": "story_reddit", "topic": "A person who discovers their cat can talk", "duration": "30", "background_video_id": "minecraft-parkour-1", "brainrotify_level": 70, "subtitle_font": "Bangers", "reddit_username": "u/SomeRedditor", "reddit_upvotes": "12.4k", "reddit_comments": "892", "webhook_url": "https://you.example.com/hooks/brainrotify" }

Field

Type

Notes

mode

string

story · story_reddit · story_messages · quiz · brainrot

topic

string

What the video is about — required

duration

string

Target length hint: 15, 30, 60 (seconds)

background_video_id

string

From GET /backgrounds

brainrotify_level

int

0–100 — how chaotic the script is

reddit_username

string?

Shown on the Reddit card (story_reddit mode)

reddit_upvotes

string?

Vote count on the card

messages_contact_name

string?

Contact name (story_messages mode)

webhook_url

string?

POSTed when job completes

status advances: queued → processing → completed | failed. video_url is a permanent CDN MP4 on completion. Failed jobs auto-refund API credits.

JSON2Video — /render

Full movie JSON with explicit coordinates, per-scene audio layers, and {{variable}} substitution. Same engine as /videos/generate but richer format.

POST

https://www.brainrotify.me/api/v1/render

Submit → 202 {job_id, status, credits_used}

GET

https://www.brainrotify.me/api/v1/render/{job_id}

Poll → {status, current_step, video_url, error}

Full example

{ "movie": { "mode": "brainrot", "title": "{{topic}} in 30s", "scenes": [ { "narration": "{{topic}} bends space and time.", "media": [ { "kind": "web_image", "search_query": "{{topic}}", "x": 0.05, "y": 0.04, "w": 0.90 }, { "kind": "web_gif", "search_query": "mind blown", "x": 0.55, "y": 0.60, "w": 0.40 } ], "audio": [{ "url": "https://example.com/whoosh.mp3", "volume": 0.4, "start_sec": 0.1 }] } ] }, "settings": { "background_video_url": "https://cdn.brainrotify.me/assets/background_videos/minecraft-parkour-1_clip.mp4", "narrator_voice_id": "default", "subtitle_font": "Impact", "words_per_subtitle": 1, "background_audio_url": "https://example.com/lofi.mp3", "background_audio_volume": 0.12, "tts_speed": 1.1 }, "variables": { "topic": "black holes" } }

Movie field

Notes

movie.scenes[].media[].kind

ai_image · web_image · web_gif

movie.scenes[].media[].x/y/w/h

Normalized 0–1 on the 1080×1920 canvas. Omit → auto layout

movie.scenes[].media[].resolved_url

Pre-fetch this URL directly (skip search) — ideal for motion_clip

movie.scenes[].audio[]

{url, volume, start_sec, duration_sec, loop} — per-scene SFX

settings.background_audio_url

Looping background music behind all scenes

variables

Dict of key → value; replaces all {{key}} in the movie JSON

Audio generation

Generate AI songs via the Suno engine. Usually returns two track variants. Failed jobs auto-refund credits.

POST

https://www.brainrotify.me/api/v1/audio/generate

Submit → 202 {job_id, status, credits_used}

GET

https://www.brainrotify.me/api/v1/audio/{job_id}

Poll → {status, tracks[], error}

POST /audio/generate body

{ "prompt": "Italian brainrot trap banger, chaotic energy", "style": "italian brainrot, trap, upbeat", "title": "My Banger", "model": "V4_5", "instrumental": false, "webhook_url": "https://you.example.com/hooks/brainrotify" }

Poll response

{ "job_id": "apiaud_abc123", "status": "completed", "tracks": [ { "audio_url": "https://cdn.suno.ai/abc.mp3", "title": "My Banger", "duration_sec": 142, "cover_image": "https://cdn.suno.ai/abc.jpg" } ], "credits_used": 2 }

Field

Type

Notes

prompt

string

Lyrics or song description — required

style

string?

Genre / style tags

model

string?

V4 · V4_5 · V4_5PLUS · V5 (default V4_5)

instrumental

bool?

Omit vocals

webhook_url

string?

POSTed with tracks on completion

Account & credits

GET

https://www.brainrotify.me/api/v1/credits/balance

Balance + plan info

GET

https://www.brainrotify.me/api/v1/credits/history

Usage grouped by endpoint (last 30 days)

GET

https://www.brainrotify.me/api/v1/account

Plan, balance, rate limit, 30-day usage

Credit costs

Operation

Credits

Standard video (brainrot, story, etc.)

Quiz / conversation video

Avatar video

AI song / lyric swap

AI image (per scene in /render)

API credits are separate from your app credit balance. Failed jobs auto-refund — you're only billed for successful generations.