Overview

The roasOS REST API makes ad creative and reads competitor ads. This section is the full reference for each endpoint.

Base URL

Send every request to this URL:

https://api.roasos.com

Authentication

Every endpoint under /v1 needs an API key. Send the key as a bearer token:

Authorization: Bearer roasos_sk_...

The same key opens the MCP server. Refer to Authentication to make a key, and to Connect an AI agent (MCP) for the agent door.

Rules for a paid request

A paid request is quote-first. It obeys three rules.

Send an Idempotency-Key header. The value is 16 to 255 characters, from letters, numbers, and the characters ., _, : and -.
Send quote_only: true to read the price. The answer is a quote, and it charges nothing.
Send the same body again with the quote_id of that quote. The answer is a job, an analysis, or an agent run.

A body that carries quote_only and quote_id together is a 400. The message is quote_id must be omitted when quote_only is true.

A free endpoint works in another way. It costs 0 credits, it needs no Idempotency-Key, and it never answers with a quote. Every read, every delete, and every write that stores your own data is free. Refer to Quotes and credits for the full rule.

One call for many generations

POST /v1/generation-batches/quotes prices a set of generations in one call. It charges nothing, and it starts nothing. The answer holds one batch_quote_id and one line for each item.

POST /v1/generation-batches confirms that quote. Send the batch_quote_id. roasOS reserves the credits and starts every item together. One batch holds 8 items at most, and both calls need an Idempotency-Key.

Each item in the answer carries its own generation_id. Read each item at GET /v1/jobs/{id}, exactly as you read a single generation. Refer to Jobs.

Groups of endpoints

Group	Purpose
Generations	Batch creates, the generation records, and the deprecated `POST /v1/generations` create path
Scenes	Your saved scenes
Avatars	Your saved avatars
Products	Your products: the photos, the facts, and the product kit
Uploads	Your own images, video, and audio on workspace CDN storage. Refer to Reference media and uploads.
Voices	Your cloned voices
Research	Search the ads that a company runs on Facebook. Refer to Research ads.
Workflows	Named jobs over the whole pipeline: analyze an ad, recast a video, animate a still, make static ads. Refer to Workflows.
Agent	Start one unattended agent run, and read it. Refer to Agent.
Skills	Your saved, reusable asks. Refer to Skills.
Brand kit	Your logo, your `colors`, your fonts, and your call to action. Refer to Brand kit.
Memory	The facts you pin, and the marketing brief. Refer to Memory.
Intelligence	What your workspace knows, compiled into documents that you and the agent read. Refer to Intelligence.
Discover	Read the roasOS library of example ads
Account	Read your credits, your usage, and your spend limits
Capabilities	Read the models and the features that your key can use
Jobs	One read model over every job. Refer to Jobs.
Catalog	Every model that roasOS can run, with its modes, fields, prices, and prompt guide
Models	One endpoint for each model. Refer to Nano Banana Pro for the guide version of one endpoint.

Hidden models

Some model endpoints in this reference have no model page in the Models section of this site. Each one belongs to a hidden model.

A hidden model keeps its price, its provider, and its catalog entry. It stays callable, and its endpoint obeys the same rules as every other model endpoint. roasOS keeps it out of the default catalog listing and out of the model pages. The model pickers in the app do not show it either.

To read a hidden model in the catalog, send GET /v1/catalog?include=hidden. The default value of include is public.

These are the hidden models and their endpoints. Every endpoint below takes a POST.

Model	Endpoint
`flux-2-max`	`/v1/image/flux-2-max`
`grok-imagine-image`	`/v1/image/grok-imagine-image`
`grok-imagine`	`/v1/video/grok-imagine`, `/v1/ugc/grok-imagine`
`maya-1`	`/v1/audio/maya-1`
`veo-3.1`	`/v1/video/veo-3.1`, `/v1/ugc/veo-3.1`
`wan-2.7`	`/v1/video/wan-2.7`, `/v1/ugc/wan-2.7`
`sora-2`	no endpoint: the catalog carries the price, and roasOS runs no call
`sora-2-pro`	no endpoint: the catalog carries the price, and roasOS runs no call

To read the price of one of these models, send GET /v1/catalog?include=hidden and read its entry. No other page of this site names a hidden model.

Changes to a published contract

roasOS adds operations and fields without warning, because an addition breaks no caller. A change that refuses a request that roasOS used to accept is different. Each one is published here, with its date and its reason.

2026-10-29 — the Kling 3 and Kling O3 endpoints are removed

These endpoints now answer 404 invalid_model: /v1/video/kling-o3-pro, /v1/video/kling-o3, /v1/video/kling-o3-4k, /v1/video/kling-3-pro, /v1/video/kling-3, /v1/video/kling-3-4k, /v1/ugc/kling-o3-pro, /v1/ugc/kling-o3, /v1/ugc/kling-o3-4k, /v1/ugc/kling-3-pro, /v1/ugc/kling-3, /v1/video-edit/kling-o3-pro and /v1/video-edit/kling-o3. /v1/generations refuses the same model ids. Use Kling 4.0 for new video and Kling 4.0 Edit for an edit. There is no 4K Kling endpoint.

POST /v1/workflows/recast and POST /v1/workflows/static-to-video refuse model: "kling-o3-pro" and model: "kling-o3". A recast with elements and no model runs on kling-4, and it takes a source of up to 30 seconds. /v1/generations with no model on a video request now runs on kling-4, not kling-3. Quote first: the prices change.

kling-3-motion and kling-avatar-v2-pro do not change.

2026-10-21 — Kling 4.0 replaces Kling 3 and Kling O3 for new video

POST /v1/video/kling-4 and POST /v1/ugc/kling-4 are new. Kling 4.0 makes 3 to 30 seconds of video at 720p or 1080p from text, from a first frame, or from reference images, reference clips and identity elements. Refer to Kling 4.0.

These endpoints are now deprecated: /v1/video/kling-o3-pro, /v1/video/kling-o3, /v1/video/kling-3-pro, /v1/video/kling-3 and the same four /v1/ugc/… endpoints. They continue to operate and their prices do not change. The catalog marks them with deprecated, and OpenAPI marks them deprecated: true.

These do not change: the Kling video-edit endpoints (/v1/video-edit/kling-o3-pro, /v1/video-edit/kling-o3), kling-3-motion, kling-3-4k, kling-o3-4k and kling-3-image. Kling 4.0 has no edit, motion-control or 4K endpoint.

A POST /v1/workflows/static-to-video request with product_id, or with a duration that Seedance does not offer, and no model, now runs on kling-4, not kling-o3-pro. Its price changes, so quote it first. To keep the old behavior, send model: "kling-o3-pro".

2026-10-04 — agent runs price at `agent-token-pricing@2026-10-04.v3`

The agent now keeps its prompt cache for one hour, not five minutes, so a run that continues after a pause reads the cache at 0.1x the input rate instead of writing it again. A one-hour cache write costs 2x the input rate, and a run meters it at that rate. Input, output and cache-read rates do not change.

2026-10-04 — the static-to-video default is Seedance 2.5

A POST /v1/workflows/static-to-video request that sends no model now runs on seedance-2.5, not kling-o3-pro, at 5 seconds when duration_seconds is omitted. A request with product_id, or with a duration that Seedance does not offer, still runs on kling-o3-pro. The price of a request with no model changes (5 seconds: 40 credits, was 15), so quote it first. To keep the old behavior, send model: "kling-o3-pro". Refer to Animate a still.

2026-10-04 — the recast default is Seedance 2.5 Edit

A POST /v1/workflows/recast request that sends no model now runs on seedance-2.5-edit, not kling-o3-pro. A request that sends elements and no model still runs on kling-o3-pro. The price of a request with no model changes, so quote it first. To keep the old behavior, send model: "kling-o3-pro". Refer to Recast a video.

2026-10-03 — the edit doors accept a Discover source again

The recast workflow, the video-edit lanes and the dub, captions, reframe, music, assembly and product-shot doors no longer answer 400 discover_source_not_allowed for a Discover creative. This change refuses nothing. You are responsible for the rights to the footage you edit. Refer to Media rights.

2026-08-21 — the raw video-edit lanes refuse a Discover source (reversed on 2026-10-03)

POST /v1/video-edit/kling-o3-pro, POST /v1/video-edit/kling-o3 and POST /v1/video-edit/gemini-omni-flash now answer 400 discover_source_not_allowed when the source video is a roasOS Discover creative. The answer names the field video_url.

The workflow above these endpoints, POST /v1/workflows/recast, already refused one. The raw lane was therefore a way around a published promise: competitor footage is read, and never edited. POST /v1/workflows/analyze still reads a Discover creative, and that is unchanged.

Refer to Media rights.

2026-08-21 — additions that refuse nothing

Change	Effect
`POST /v1/workflows/statics`	A new workflow. Refer to Make static ads.
`POST /v1/image-edit/bria-product-shot`	A new model endpoint. Its plain-text contract is `image-edit/bria-product-shot`.
`model` on `POST /v1/workflows/recast`	A tier choice, `kling-o3-pro` or `kling-o3`. The default does not move, so no price of an existing call changes.
`media_rights` on `POST /v1/workflows/recast`	Required when the swap target is an uploaded face. A recast onto a gallery avatar is unchanged.
`media_rights` on `POST /v1/lipsync/veed-lipsync-v2`	Optional today, and required in a later release. roasOS records the attestation when you send one. Refer to Media rights.
`num_images` on `POST /v1/reframe/ideogram-v3`	Now 1 to 4, and no longer pinned to 1. The count multiplies the price, so the default stays 1. Quote the request to read the exact price.

Availability

Some operations are internal, and this reference does not publish them. To read the operations that your key can use, send GET /v1/capabilities.

This reference is generated from the roasOS OpenAPI document. The document is at https://docs.roasos.com/openapi.json. It holds the public operations only.

On this page