REST API v1 · Reference

API Documentation

Everything you need to generate short-form videos over HTTP. Authenticate with a scoped key, POST a project, and poll a render.

Get an API key← Brainrot APIhttps://www.brainrotshorts.com/api/v1

Overview

The Brainrot Shorts REST API lets you generate short-form vertical videos programmatically — AI brainrot dialogue videos, Reddit story videos, and AI voice-over videos. It's the same engine as the app, exposed over HTTP.

All requests are made to https://www.brainrotshorts.com/api/v1. REST API access is available on the Creator and Pro plans. New to the API? Start with the Brainrot API overview.

Auth

Authentication

Create a REST API key in the API dashboard. The full key (prefixed brs_) is shown once — store it securely. Send it in the X-API-Key header on every request. REST keys are separate from MCP / agent keys and are scoped specifically to this API.

Authenticated request
curl https://www.brainrotshorts.com/api/v1/me \
  -H "X-API-Key: brs_your_api_key"

Get started

Quickstart

Create a voice-over project, then approve, render, and poll for the finished MP4.

1 · Create a project
curl https://www.brainrotshorts.com/api/v1/voiceover/projects \
  -H "X-API-Key: $BRS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clip-001" \
  -d '{
    "title": "Daily AI news",
    "voiceId": "peter_griffin",
    "backgroundVideoUrl": "https://cdn.example.com/gameplay.mp4",
    "scenes": [
      { "text": "Everyone thinks AI replaces video editors." },
      { "text": "The real edge is shipping ten variants before lunch." }
    ]
  }'
2 · Render & poll
# 1. Approve + start the render
curl https://www.brainrotshorts.com/api/v1/projects/proj_a1b2c3/render \
  -H "X-API-Key: $BRS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "approved": true }'

# 2. Poll until status is "done", then read outputUrl
curl https://www.brainrotshorts.com/api/v1/projects/proj_a1b2c3/render \
  -H "X-API-Key: $BRS_API_KEY"

Conventions

Response format

Every response is JSON. Successful responses wrap the payload in data; errors use an error object. Both always include a requestId.

Success
{
  "data": { /* endpoint payload */ },
  "requestId": "req_5f3c0e9d"
}
Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation.",
    "details": [
      { "path": "scenes", "code": "too_small", "message": "Array must contain at least 1 element(s)" }
    ]
  },
  "requestId": "req_5f3c0e9d"
}

Response headers

X-Request-Id

Unique ID for the request (also in the body as requestId). Quote it in support requests.

X-RateLimit-Limit

Total requests allowed in the current 24h window for this key.

X-RateLimit-Remaining

Requests remaining in the current window.

X-RateLimit-Reset

ISO-8601 timestamp when the window resets.

X-RateLimit-Window

Window length in seconds (86400).

X-API-Tier

Plan tier resolved for the key (Creator or Pro).

X-Idempotent-Replay

Present and true when a response was replayed from an Idempotency-Key.

Retry-After

On a 429, seconds to wait before retrying.

Failures

Errors

Errors return the appropriate HTTP status and a stable error.code you can switch on.

CodeStatusMeaning
MISSING_API_KEY401

No X-API-Key header was sent.

INVALID_API_KEY401

Key is unknown, disabled, expired, or not scoped for REST access.

FORBIDDEN403

Your plan does not include REST API access (Creator/Pro only).

INSUFFICIENT_CREDITS402

Not enough credits for a render, script, or audio action.

VALIDATION_ERROR400

Body is not valid JSON or failed schema validation. See details[].

UNSUPPORTED_VIDEO_TYPE400

The project's kind is not valid for this endpoint.

NOT_FOUND404

Project, scene, render, or route does not exist for this account.

RATE_LIMITED429

Daily request quota for the key is exhausted. See Retry-After.

IDEMPOTENCY_CONFLICT409

Idempotency-Key was reused with a different request body.

INTERNAL_ERROR500

Unexpected server error. Safe to retry with an Idempotency-Key.

Quotas

Rate limits

Requests are metered per key on a rolling 24-hour UTC window:

50 / day

Creator

200 / day

Pro

Read X-RateLimit-Remaining to track usage; a 429 response includes a Retry-After header. Status polls count toward the quota, so poll conservatively. Renders, script generation, and narration audio also consume your account's credits.

Safe retries

Idempotency

Any mutating POST accepts an optional Idempotency-Key header. Retrying with the same key and body within 24 hours replays the original response (flagged with X-Idempotent-Replay) instead of creating a duplicate. Reusing a key with a different body returns IDEMPOTENCY_CONFLICT.

Idempotent create
curl https://www.brainrotshorts.com/api/v1/voiceover/projects \
  -H "X-API-Key: $BRS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{ "title": "Daily AI news", "scenes": [ { "text": "..." } ] }'

Model

Core concepts

  • Project — a video and its config. Each has a kind (brainrot, reddit-story, or ai-voice-over-video) and a status.
  • Scene / block — the ordered units inside a project that carry the script text and per-scene settings.
  • Render — a job that produces the final MP4. Start it, then poll until status: "done" and read outputUrl.
  • Audio job — narration generation runs async; poll GET /audio/jobs/{jobId}.

Endpoints

Account & catalog

Read your account context and the catalogs of voices, backgrounds, and caption styles you can reference by ID.

GET/api/v1/me

Get the authenticated account.

Example response
{
  "data": { "userId": "usr_123", "plan": "creator" },
  "requestId": "req_5f3c0e9d"
}

https://www.brainrotshorts.com/api/v1/me

GET/api/v1/catalog/characters

List the characters and voices available to your plan.

https://www.brainrotshorts.com/api/v1/catalog/characters

GET/api/v1/catalog/backgrounds

List gameplay/background videos you can attach by ID.

https://www.brainrotshorts.com/api/v1/catalog/backgrounds

GET/api/v1/catalog/caption-styles

List the built-in caption style presets.

https://www.brainrotshorts.com/api/v1/catalog/caption-styles

Endpoints

Projects & renders

Shared lifecycle endpoints. Only brainrot, reddit-story, and ai-voice-over-video projects are visible over the REST API.

GET/api/v1/projects

List your API-visible projects with their latest render.

Example response
{
  "data": { "projects": [ { "id": "proj_a1b2c3", "kind": "ai-voice-over-video", "status": "draft", "latestRender": null } ] },
  "requestId": "req_5f3c0e9d"
}

https://www.brainrotshorts.com/api/v1/projects

GET/api/v1/projects/{projectId}

Get a single project by ID.

Path parameters

projectIdstringrequired

The project ID.

DELETE/api/v1/projects/{projectId}

Delete a project.

Path parameters

projectIdstringrequired

The project ID.

POST/api/v1/projects/{projectId}/render

Approve and start a render.

Renders consume credits. Send an Idempotency-Key so retries don't start duplicate renders.

Path parameters

projectIdstringrequired

The project ID.

Body parameters

approvedboolean

Must be true to start the render. Defaults to false.

Example request
curl https://www.brainrotshorts.com/api/v1/projects/proj_a1b2c3/render \
  -H "X-API-Key: $BRS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: render-001" \
  -d '{ "approved": true }'
Example response
{
  "data": { "render": { "id": "rnd_99", "status": "rendering", "progress": 0.0 } },
  "requestId": "req_5f3c0e9d"
}
GET/api/v1/projects/{projectId}/render

Get the latest render status for a project (poll this).

Path parameters

projectIdstringrequired

The project ID.

Example response
{
  "data": { "render": { "id": "rnd_99", "status": "done", "progress": 1, "outputUrl": "https://.../proj_a1b2c3.mp4" } },
  "requestId": "req_5f3c0e9d"
}
GET/api/v1/renders/{renderId}

Get a specific render by its ID.

Path parameters

renderIdstringrequired

The render ID.

GET/api/v1/projects/{projectId}/output

Get the latest finished output URL for a project.

Path parameters

projectIdstringrequired

The project ID.

GET/api/v1/audio/jobs/{jobId}

Get the status of a narration audio generation job.

Path parameters

jobIdstringrequired

The audio job ID returned by a scene audio call.

Endpoints

AI Brainrot

Gameplay-background dialogue videos with AI voiceover and word-by-word captions.

POST/api/v1/brainrot/projects

Create a brainrot project.

Provide simple settings to start a draft, or pass a full promptJson scene config to create a ready-to-render project.

Body parameters

titlestring

Project title (max 120 chars).

backgroundVideoIdstring

ID from GET /catalog/backgrounds.

characterIdstring

ID from GET /catalog/characters.

captionStyleobject

Caption styling object. List valid presets via GET /catalog/caption-styles.

captionGroupingobject

Controls how words are grouped into caption chunks.

promptJsonobject

Full project config (backgroundColor, scenes[]). When present, creates a complete project.

Example request
curl https://www.brainrotshorts.com/api/v1/brainrot/projects \
  -H "X-API-Key: $BRS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Did you know?", "characterId": "peter_griffin" }'
PATCH/api/v1/brainrot/projects/{projectId}

Update a brainrot project.

Path parameters

projectIdstringrequired

The project ID.

Body parameters

titlestring

New title (max 120 chars).

captionStyleobject

Caption styling object. List valid presets via GET /catalog/caption-styles.

captionGroupingobject

Controls how words are grouped into caption chunks.

backgroundColorstring

Background color for the project.

watermarkEnabledboolean

Toggle the watermark.

promptJsonobject

Replace the full scene config.

PATCH/api/v1/brainrot/projects/{projectId}/scenes/{sceneId}

Update a single scene.

Path parameters

projectIdstringrequired

The project ID.

sceneIdstringrequired

The scene ID.

Body parameters

characterIdstring

Character for the scene.

backgroundVideoIdstring

Background by catalog ID.

backgroundVideoUrlstring

Background by direct URL.

characterEntranceEnabledboolean

Toggle the character entrance animation.

characterEntrancePresetstring

Entrance animation preset.

characterEntranceSoundEnabledboolean

Toggle the entrance sound.

characterPositionobject

Character position.

characterScalenumber

Character scale (> 0).

captionPositionYnumber

Vertical caption position, 0–1.

voiceEnabledboolean

Toggle voiceover for the scene.

POST/api/v1/brainrot/scripts/ideas

Generate script ideas for a niche.

Body parameters

nichestringrequired

The niche to ideate around (max 200 chars).

https://www.brainrotshorts.com/api/v1/brainrot/scripts/ideas

POST/api/v1/brainrot/projects/{projectId}/scripts/generate

Generate a full script for a project.

Path parameters

projectIdstringrequired

The project ID.

Body parameters

nichestringrequired

Niche (max 200 chars).

ideastringrequired

The specific idea to script (max 500 chars).

charactersarray

1–4 characters to cast in the dialogue.

POST/api/v1/brainrot/projects/{projectId}/scripts/apply

Apply a script to a project as scenes.

Path parameters

projectIdstringrequired

The project ID.

Body parameters

titlestring

Optional title (max 120 chars).

scriptarrayrequired

1–40 script lines to turn into scenes.

POST/api/v1/brainrot/projects/{projectId}/scenes/{sceneId}/audio

Generate narration audio for a scene.

Consumes credits. Returns an audio job — poll GET /audio/jobs/{jobId}.

Path parameters

projectIdstringrequired

The project ID.

sceneIdstringrequired

The scene ID.

Endpoints

Reddit Videos

Narrated Reddit story videos from a Reddit URL, a raw prompt, or an explicit script/blocks payload.

POST/api/v1/reddit/posts/fetch

Fetch a Reddit post for use in a story video.

Body parameters

urlstringrequired

A valid Reddit post URL.

https://www.brainrotshorts.com/api/v1/reddit/posts/fetch

POST/api/v1/reddit/scripts/generate

Generate a Reddit story script from a description.

Body parameters

descriptionstringrequired

What the story is about (max 2000 chars).

stylestring

Optional style hint (max 100 chars).

durationSecondsnumber

Target length 10–120. Defaults to 90.

https://www.brainrotshorts.com/api/v1/reddit/scripts/generate

POST/api/v1/reddit/posts/repurpose

Repurpose an existing Reddit post into a script.

Body parameters

originalPostobjectrequired

{ subreddit, username, title, selftext, upvotes, comments }.

mode"repurpose" | "longer"required

Repurpose verbatim-ish or expand into a longer story.

durationSecondsnumber

Target length 10–120. Defaults to 60.

https://www.brainrotshorts.com/api/v1/reddit/posts/repurpose

POST/api/v1/reddit/projects

Create a Reddit story project.

Provide exactly one of script or blocks, plus optional settings.

Body parameters

titlestring

Project title (max 120 chars).

voiceIdstring | null

Narrator voice.

backgroundVideoUrlstring | null

Background by URL.

backgroundVideoIdstring

Background by catalog ID.

captionStyleobject

Caption styling object. List valid presets via GET /catalog/caption-styles.

captionGroupingobject

Controls how words are grouped into caption chunks.

backgroundMusicobject | null

Background music config.

playbackRatenumber

Speed 1–2.

watermarkEnabledboolean

Toggle watermark.

captionPositionYnumber

Caption position, 0–1.

scriptobject

A generated Reddit script object (mutually exclusive with blocks).

blocksarray

Explicit story blocks (mutually exclusive with script).

https://www.brainrotshorts.com/api/v1/reddit/projects

PATCH/api/v1/reddit/projects/{projectId}

Update a Reddit story project.

Path parameters

projectIdstringrequired

The project ID.

Body parameters

(settings)object

Any of the create settings above.

script | blocksobject | array

Optionally replace the script or blocks (not both).

POST/api/v1/reddit/videos/from-prompt

Create a Reddit video from a text prompt in one call.

Body parameters

descriptionstringrequired

What the story is about (max 2000 chars).

stylestring

Optional style hint.

durationSecondsnumber

Target length 10–120. Defaults to 90.

(settings)object

Any Reddit project settings (voiceId, background, captions...).

approvedboolean

Start a render immediately. Defaults to false.

https://www.brainrotshorts.com/api/v1/reddit/videos/from-prompt

POST/api/v1/reddit/videos/from-url

Create a Reddit video from a Reddit URL in one call.

Body parameters

urlstringrequired

A valid Reddit post URL.

originalPostobject

Optional pre-fetched post payload.

mode"repurpose" | "longer"

Defaults to repurpose.

durationSecondsnumber

Target length 10–120. Defaults to 60.

(settings)object

Any Reddit project settings.

approvedboolean

Start a render immediately. Defaults to false.

Example request
curl https://www.brainrotshorts.com/api/v1/reddit/videos/from-url \
  -H "X-API-Key: $BRS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reddit-001" \
  -d '{ "url": "https://www.reddit.com/r/AmItheAsshole/comments/abc123/", "approved": true }'
POST/api/v1/reddit/projects/{projectId}/blocks/{blockId}/audio

Generate narration audio for a Reddit block.

Path parameters

projectIdstringrequired

The project ID.

blockIdstringrequired

The block ID.

Endpoints

AI Voice Over

Scenes of text narrated over any background video, with tunable captions and playback.

POST/api/v1/voiceover/scripts/generate

Generate a voice-over script from a description.

Body parameters

descriptionstringrequired

What the video is about (max 2000 chars).

stylestring

Optional style hint (max 100 chars).

durationSecondsnumber

Target length 10–120. Defaults to 60.

https://www.brainrotshorts.com/api/v1/voiceover/scripts/generate

POST/api/v1/voiceover/projects

Create an AI voice-over project.

Body parameters

titlestring

Project title (max 120 chars).

voiceIdstring | null

Narrator voice ID.

backgroundVideoUrlstring | null

Background video URL.

captionStyleobject

Caption styling object. List valid presets via GET /catalog/caption-styles.

captionGroupingobject

Controls how words are grouped into caption chunks.

captionPositionYnumber

Caption position, 0–1.

backgroundMusicobject

Background music config.

playbackRatenumber

Speed 1–2.

watermarkEnabledboolean

Toggle watermark.

scenesarrayrequired

≥1 scene: { text (required), id?, narrationAudioUrl?, generatedCaptions?, durationInSeconds? }.

Example request
curl https://www.brainrotshorts.com/api/v1/voiceover/projects \
  -H "X-API-Key: $BRS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clip-001" \
  -d '{
    "title": "Daily AI news",
    "voiceId": "peter_griffin",
    "backgroundVideoUrl": "https://cdn.example.com/gameplay.mp4",
    "scenes": [
      { "text": "Everyone thinks AI replaces video editors." },
      { "text": "The real edge is shipping ten variants before lunch." }
    ]
  }'
Example response
{
  "data": { "project": { "id": "proj_a1b2c3", "kind": "ai-voice-over-video", "status": "draft" } },
  "requestId": "req_5f3c0e9d"
}
PATCH/api/v1/voiceover/projects/{projectId}

Update an AI voice-over project.

Path parameters

projectIdstringrequired

The project ID.

Body parameters

(any create field)object

Any field from create. scenes, if sent, must contain ≥1 scene.

POST/api/v1/voiceover/projects/{projectId}/scenes/{sceneId}/audio

Generate narration audio for a voice-over scene.

Path parameters

projectIdstringrequired

The project ID.

sceneIdstringrequired

The scene ID.

Recipes

Workflows

AI Voice Over → MP4

  1. POST /voiceover/projects with your scenes → get a projectId.
  2. POST /projects/{projectId}/render with { approved: true }.
  3. Poll GET /projects/{projectId}/render until done, then read outputUrl.

Reddit URL → MP4 (one call)

  1. POST /reddit/videos/from-url with the URL and { approved: true }.
  2. Poll the render and read outputUrl.

AI Brainrot from a niche

  1. POST /brainrot/projects → projectId.
  2. POST /brainrot/projects/{projectId}/scripts/generate, then .../scripts/apply.
  3. Render and poll as above.