What the Developer API Does
Render BallEngine videos from your own app, script or AI agent: what it is, who can use it, and where everything lives.
One request in, one MP4 out
The Developer API lets your own software create BallEngine videos without opening the Studio. You send one request that describes the video you want (length, shape, mode, theme, caption, speed and so on). Our cloud renderer builds the scene, renders it, and gives you back a finished MP4.
Every API video is randomized from the settings you send, so two requests with the same settings give two different videos. If you like one, reuse its seed to get the same video again.
Renders are paid for with render credits: 1 credit buys 30 seconds of 720p 30 fps video, and 1080p 60 fps (set with the quality field) uses 2 credits per 30 seconds. You can ask for any length from 5 to 300 seconds.
Who can use it
API access is invite-only for now. Our team switches it on for each account by hand; buying credits does not turn it on. Until then, the Developer page (/developer) shows a Request API Access button (it opens support, where you tell us what you are building) and the credit packs you can buy. Any signed-in account can buy credits; they pay for cloud renders in the Studio, and for API renders once access is on.
| What you want to do | What you need |
|---|---|
| Read the API documentation | Nothing. /developer/docs is public. |
| Buy render credits | Any signed-in account. Studio cloud renders are watermarked without a paid Studio plan. |
| Create API keys and call the API | API access, which our team switches on by invitation. |
| Put the BallEngine player on your own website (BYOBE) | An invitation. We set up your site and its key for you; see the Embed player section. |
| Receive webhooks | API access, plus an https server of your own to receive them. |
Embed player (BYOBE, invite-only)
BYOBE (Build Your Own Ball Engine) puts a BallEngine mode on your own website with one iframe. Your visitors watch it, press Randomize, and download the video, which is made on their own device, so it uses no render credits. The player runs inside our frame, so your page keeps its own design and the player is never affected by your styles. It is invite-only: we create your site, register the websites allowed to show it, and give you its public key (be_pk_...). Pick a plan you would want on /developer and press Confirm interest to join the queue. The player takes the same look settings as a cloud render (theme, palette, title_text, watermark_text, speed, ball_count, gravity, sound_effect, config_overrides) in its URL or in a set-settings message, so your site and your rendered videos match. Once invited, the quickest way in is the Copy AI prompt button on /developer: paste it into Claude, ChatGPT or Cursor inside your website project and the assistant adds the player for you (the same guide is public at /byobe-guide.txt).
<iframe src="https://ballengine.app/embed?key=be_pk_...&mode=FLAG_BATTLE&visitor=USER_ID&duration=15" style="width:100%;aspect-ratio:9/16;border:0"></iframe>
The public key only works on the websites registered for it: a browser refuses to show the player anywhere else. Cloud renders for visitors on slow devices are made from your own server with your secret key (POST /api/v1/videos), never from the page.
| Part | What it does |
|---|---|
| mode | Any finished mode, by key (FLAG_BATTLE) or by its page name (flag-battle). |
| visitor (optional) | Your own id for the visitor. Used for a per-visitor monthly limit if your site has one. |
| duration (optional) | Length of a downloaded video, 5 to 60 seconds. 15 if left out. |
| Monthly videos | Each finished download counts once against the monthly pool of your site. A cancelled or failed one does not. |
| Messages to your page | The player sends ready, randomized, export-progress, export-done (with the MP4 file, so you can upload it), export-failed and limit-reached through postMessage. |
| Messages from your page | Send {target: "ballengine", type: "randomize"}, {type: "export"} or {type: "set-mode", mode: "RHYTHMIC"} to drive the player from your own buttons. The ready message lists every mode for a mode picker. |
Where everything lives
There are two pages. The Developer page (/developer, reached from your Dashboard) is where you manage your account. The API Docs page (/developer/docs) is the full technical reference with every field, example requests and responses, and a code sample for checking webhook signatures.
| Section of /developer | What it shows |
|---|---|
| Credit balance | Credits you can spend through the API, a Buy credits button, and a log of recent purchases, renders and credits returned. |
| API Keys | Create a key (with an optional name), see each key's start, status, created date and last use, and revoke keys. |
| Webhooks | Add the https address of your server, pick the events you want, send a test, get a new signing secret, and see recent deliveries. |
| Connect to Claude, ChatGPT & AI Agents | Three ways to hand the API to an AI tool: Copy AI Prompt, Copy OpenAPI URL and Copy MCP URL. |
| Recent API Renders | Your last renders with status, length, date and a Download button once they are done. |
Tip
- The API Docs button at the top of /developer opens the full reference. This Help section explains the ideas and the common problems; it does not repeat every field.
- The Developer page refreshes itself every 20 seconds. Use the Refresh button if you want to see a change right away.
What you can control in a request
A request can set the video length, aspect ratio, simulation mode (or RANDOM), a visual theme or your own colour palette, an on-screen title, a watermark such as your handle, the simulation speed, how deeply the look is randomized, and a seed. You can also attach your own metadata (for example an order number) that comes back with the video and in its webhooks.
For music, leave the track out and an original track is generated for the video, or pass a link to audio you have uploaded to BallEngine. Named tracks from the old built-in catalogue are no longer available for new work.
The exact field names, allowed values and defaults are on /developer/docs.
| Aspect ratio | Output size | Typical use |
|---|---|---|
| 9:16 (default) | 1080x1920 | TikTok, YouTube Shorts, Instagram Reels |
| 16:9 | 1920x1080 | YouTube |
| 1:1 | 1080x1080 | Square posts |
| 4:5 | 1080x1350 | Portrait feed posts |
| 3:4 | 1080x1440 | Tall posts and tablets |
Tip
- 9:16 is the default and the shape every mode is designed around first. Other ratios are laid out for their own shape, but titles near the top and counters near the bottom have the most room in 9:16. If framing matters for your project, render one short clip in your ratio and check it before you render in bulk.
- API renders come out as MP4 at up to 1080 pixels on the short side.
Using the API from an AI tool
The "Connect to Claude, ChatGPT & AI Agents" panel on /developer gives you three ready-made ways in:
| Option | What it copies | Use it for |
|---|---|---|
| Option 1: Copy AI Prompt | A prompt that teaches a chat assistant how to call the API, with your key in it. | Pasting into a chat assistant that can make web requests. |
| Option 2: Copy OpenAPI URL | The address of the machine-readable API description. | Custom GPTs, custom tools and automation platforms that import OpenAPI. |
| Option 3: Copy MCP URL | The address of our hosted MCP endpoint. | Desktop AI apps and code editors that support remote MCP servers. Send your key as a bearer token. |
Tip
- The copied AI prompt contains a live secret key. Anyone who runs the tool you paste it into can use it. If you stop trusting where a prompt has been, revoke that key and create a new one.
- Through the MCP endpoint an AI tool can create a video, check it, list your videos, cancel a queued one and estimate the cost of a render.
More from BallEngine
Guides, plans and answers for making your videos.