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 turns on by itself the first time you buy credits: no request or approval is needed. Until then, the Developer page (/developer) shows a Request API Access button and the credit packs you can buy. Any signed-in account can buy credits, and they also pay for cloud renders in the Studio.
| 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 turns on when you buy credits. |
| Receive webhooks | API access, plus an https server of your own to receive them. |
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.