roasOS API

roasOS is one API for generating paid creative — images, video, UGC ads, lipsync, and audio — and for researching the ads your competitors run.

Every paid action is quote-first: send quote_only: true to see the price for free, then send the same request with the returned quote_id to run it. Confirming is the only step that spends credits.

New here? Start with the Guides.

A few operations are marked internal and are not launch-public yet — call GET /v1/capabilities to see what is live for your key.

Authentication

All /v1/* endpoints require a Bearer token:

Authorization: Bearer roasos_sk_...

API keys can be created in your workspace settings (Growth or Scale plan required).

Rate Limits

• Read endpoints (GET): 60 requests/minute
• Write endpoints (POST): 10 requests/minute

Rate limit headers are included in responses after successful API-key authentication: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Webhooks

Pass a webhook_url when creating a generation to receive a POST callback when it completes.

Every delivery includes these headers:

• X-RoasOS-Signature: v1=<hex> — HMAC-SHA256, in lowercase hex, of <timestamp>.<raw-request-body> keyed by your API key’s webhook secret.
• X-RoasOS-Timestamp: unix seconds when this signature was generated.
• X-RoasOS-Delivery-Id: stable id for the delivery; identical across retries. Use it to deduplicate.

Verify the timestamp is recent, compute HMAC_SHA256(secret, timestamp + "." + rawBody) as lowercase hex over the raw body, and constant-time compare it with the v1= signature.

Discover

Browse ad creatives from the cached ad library.

• GETSearch the ad library/v1/discover/items
• GETGet one ad/v1/discover/items/{id}

Capabilities

See which models and operations are available.

• GETList platform capabilities/v1/capabilities

Research

Research the ads your competitors are running.

• POSTQuote or submit a Research job/v1/research/jobs
• GETGet a Research job/v1/research/jobs/{id}
• GETGet Research job status/v1/research/jobs/{id}/status
• GETGet research results/v1/research/jobs/{id}/result

Generations

Create images, video, audio, and lipsync — the core of the API. Quote first, then confirm to run.

• POSTQuote a batch/v1/generation-batches/quotes
• POSTRun a batch/v1/generation-batches
• GETList generations/v1/generations
• POSTCreate a generation/v1/generations
• GETGet generation details/v1/generations/{id}
• DELETEDelete a generation/v1/generations/{id}

Avatars

Your saved avatars.

• GETList avatars/v1/avatars
• GETGet avatar details/v1/avatars/{id}
• DELETEDelete an avatar/v1/avatars/{id}

Scenes

Create and manage scenes.

• GETList scenes/v1/scenes
• POSTCreate a scene/v1/scenes
• GETGet scene details/v1/scenes/{id}
• DELETEDelete a scene/v1/scenes/{id}

Account

Your balance, usage, spend limits, and billing history.

• GETGet account info and credit balance/v1/account
• GETGet API key spend limits/v1/limits
• GETGet credit usage history/v1/account/usage
• GETList billing history/v1/account/ledger
• GETSummarize usage/v1/account/usage/summary