--- title: "Overview" description: "The structure and the rules of the roasOS REST API." url: https://docs.roasos.com/api-reference/overview --- # 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: ```bash Authorization: Bearer roasos_sk_... ``` The same key opens the MCP server. Refer to [Authentication](/authentication) to make a key, and to [Connect an AI agent (MCP)](/mcp) for the agent door. ## Rules for a paid request A paid request is quote-first. It obeys three rules. 1. Send an `Idempotency-Key` header. The value is 16 to 255 characters, from letters, numbers, and the characters `.`, `_`, `:` and `-`. 2. Send `quote_only: true` to read the price. The answer is a quote, and it charges nothing. 3. 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](/concepts/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](/concepts/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](/concepts/product-kits) | | Uploads | Your own images, video, and audio on workspace CDN storage. Refer to [Reference media and uploads](/concepts/reference-media). | | Voices | Your cloned voices | | Research | Search the ads that a company runs on Facebook. Refer to [Research ads](/workflows/research-ads). | | Workflows | Named jobs over the whole pipeline: analyze an ad, recast a video, animate a still, make static ads. Refer to [Workflows](/workflows). | | Agent | Start one unattended agent run, and read it. Refer to [Agent](/agent). | | Skills | Your saved, reusable asks. Refer to [Skills](/agent/skills). | | Brand kit | Your logo, your `colors`, your fonts, and your call to action. Refer to [Brand kit](/brand/brand-kit). | | Memory | The facts you pin, and the marketing brief. Refer to [Memory](/brand/memory). | | Intelligence | What your workspace knows, compiled into documents that you and the agent read. Refer to [Intelligence](/brand/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](/concepts/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](/models/image/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](/models/video/kling-4) for new video and [Kling 4.0 Edit](/models/video-edit/kling-4) 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](/models/video/kling-4). 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](/workflows/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](/workflows/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](/concepts/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](/concepts/media-rights). ### 2026-08-21 — additions that refuse nothing | Change | Effect | | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST /v1/workflows/statics` | A new workflow. Refer to [Make static ads](/workflows/make-static-ads). | | `POST /v1/image-edit/bria-product-shot` | A new model endpoint. Its plain-text contract is [`image-edit/bria-product-shot`](https://docs.roasos.com/models/image-edit/bria-product-shot/llms.txt). | | `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](/concepts/media-rights#the-addition-veed-lipsync-v2-accepts-a-consent-record). | | `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`](https://docs.roasos.com/openapi.json). It holds the public operations only.