One API. Every surface.
Everything you can do in the Cleom app, you'll be able to do over HTTPS. Generate ad campaigns and videos from your own pipeline, with your game's brief and brand keeping every output consistent. The API is coming soon — today, Cleom runs through the app, starting with Ad Campaigns. Request early access below.
A REST API built for production pipelines
The Cleom API is a conventional REST API: predictable resource-oriented URLs, JSON request and response bodies, and standard HTTP status codes. Anything you generate through the API lands in the same Library as the rest of your workspace, attached to the same Game Profile, drawing from the same credit balance. There is no separate "API tier" — it's the same engine, exposed to your build scripts, CI jobs, LiveOps tooling and internal dashboards.
All requests are served over TLS from a single base URL:
# Base URL https://api.cleomai.com/v1
Generation is asynchronous by design. You submit a request, get back a generation object immediately with the estimated cost, and production starts once the request clears review — you always see the price before anything renders. Then either poll GET /generations/:id or let a webhook push the finished result to you. Most teams wire the webhook once and never poll again.
Bearer keys, scoped to your workspace
Authenticate every request with an API key passed as a Bearer token in the Authorization header. Keys are issued per workspace from your dashboard, can be named, scoped and rotated independently, and are shown exactly once at creation — store them in your secret manager, never in client-side code or public repos.
# Authenticated request curl https://api.cleomai.com/v1/games \ -H "Authorization: Bearer clm_live_8f2kq9x1m4p7w3n6" \ -H "Content-Type: application/json"
Test-mode keys (clm_test_…) hit the full API surface without consuming credits or producing renders — ideal for integration tests and staging environments. A request with a missing or invalid key returns 401; a valid key without permission for the resource returns 403.
The core surface
Six endpoints cover the whole production loop: register your game, fire generations, track them, and pull everything back out of the Library.
POST /campaigns Generate an ad campaign — one brief, 10–200 variants POST /videos Prompt-to-video via Create — Model Routing picks the model GET /generations/:id Poll any job — status, credits used, output URLs GET /library Query every output, filterable by game, type, date GET /games List the Game Profiles in your workspace POST /games Create a Game Profile — brief, brand, references
Every generation endpoint accepts a game_id, so the engine can draw on your game's brief, brand and references automatically — the same context the app uses. Endpoints for Steam Page, Store Kit, Asset Lab and Insights will follow as those surfaces launch.
Generate a campaign in one call
Here's a complete round trip for POST /campaigns: a wishlist push with twelve variants across three aspect ratios, briefed in plain English.
POST /v1/campaigns
{
"game_id": "game_8fk2hq7w",
"objective": "wishlists",
"brief": "Launch push for the Frostbound update. Lean into
the new ice biome and co-op raids. Dark, cinematic,
UI-free hooks in the first second.",
"formats": ["9:16", "1:1", "16:9"],
"variants": 12,
"platforms": ["tiktok", "meta", "youtube"],
"webhook_url": "https://ci.yourstudio.com/hooks/cleom"
}{
"id": "gen_01j9x7m2kq4t",
"object": "generation",
"type": "campaign",
"status": "queued",
"game_id": "game_8fk2hq7w",
"estimated_credits": 240,
"created_at": "2026-06-10T14:32:08Z",
"links": {
"self": "https://api.cleomai.com/v1/generations/gen_01j9x7m2kq4t"
}
}The response shows the estimated cost up front, and production starts once the request clears review. When the job finishes, status flips to completed and the generation object carries an outputs array with signed download URLs for every variant — each delivered separately — plus the exact credits consumed.
Get pushed, don't poll
Register a webhook endpoint per workspace (or pass webhook_url per request) and Cleom will POST you a signed event the moment a job lands. The one you'll care about most is generation.completed:
# Event: generation.completed
{
"event": "generation.completed",
"created_at": "2026-06-10T14:41:55Z",
"data": {
"id": "gen_01j9x7m2kq4t",
"type": "campaign",
"status": "completed",
"credits_used": 236,
"outputs": [
{ "format": "9:16", "url": "https://cdn.cleomai.com/o/…" },
{ "format": "1:1", "url": "https://cdn.cleomai.com/o/…" }
]
}
}Every delivery is signed with an HMAC header so you can verify it came from us, and failed deliveries are retried with exponential backoff for 24 hours. generation.failed — which also confirms the automatic credit refund for the failed job — and credits.low events round out the set.
Official SDKs, shipping with the API
JavaScript / TypeScript — @cleom/sdk
Fully typed client for Node and edge runtimes. Async generation helpers, built-in webhook signature verification, first-class support for Next.js and serverless deploys.
Python — cleom
Sync and async clients with typed models. Built for build pipelines, LiveOps automation and notebooks — pip install cleom and go.
Raw REST, always
The SDKs are convenience, not requirement. Any language that speaks HTTPS and JSON gets the full surface — the OpenAPI spec will be published when the API ships.
Rate limits, credits and versioning
Rate limits
60 requests per minute per workspace when the API ships, with up to 10 generations running concurrently. Every response includes X-RateLimit-Remaining and X-RateLimit-Reset headers; bursting past the limit returns 429 with a Retry-After. Higher ceilings are available for studios shipping at volume — talk to us.
Credit metering
API usage draws from the same prepaid credit balance as the app: $10 for 1K credits, $45 for 5K, $160 for 20K, $699 for 100K — and credits never expire. Each generation response reports estimated_credits up front and credits_used on completion, so cost tracking is built into the objects you already store. Failed jobs refund their credits automatically. No seats, no platform fee — you pay for what renders.
Versioning
The major version lives in the path — /v1 — and stays stable. Additive changes (new fields, new endpoints, new event types) ship without notice and won't break a well-built integration. Breaking changes only ever arrive as a new major version, with the previous one supported for at least 12 months after deprecation is announced in the changelog.
Build on the engine.
The API is coming soon. Get on the early-access list and we'll send keys, docs and the OpenAPI spec the moment they're live. In the meantime, Ad Campaigns is live in the app — one brief in, 10–200 ad variants out.
Questions about the API? hello@cleomai.com