--- title: "Workflows" description: "Popular creative jobs, each as one API call." url: https://docs.roasos.com/workflows --- # Workflows A workflow is a named operation over the whole roasOS pipeline. It is not a model. A workflow does in one call what several calls did before it. You send what you want. roasOS chooses the pipeline, the model and the media roles. ## The seven workflows | Workflow | Path | What it does | | --------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------ | | [Analyze an ad](/workflows/analyze-an-ad) | `POST /v1/workflows/analyze` | Break one ad into its structure: the shots, the transcript, the style and the insights. | | [Remix an ad](/workflows/remix-an-ad) | `POST /v1/workflows/remix` | Analyze one ad, storyboard the same structure with your product and your person, and render it. | | [Recast a video](/workflows/recast-a-video) | `POST /v1/workflows/recast` | Put your own person and your own product into a video that your workspace owns. | | [Animate a still](/workflows/animate-a-still) | `POST /v1/workflows/static-to-video` | Turn one still image into one video. | | [Extend a video](/workflows/extend-a-video) | `POST /v1/workflows/extend` | Continue one video from its last frame and get one longer clip. | | [Extract a brand](/workflows/extract-a-brand) | `POST /v1/workflows/extract-brand` | Read one brand from its own website: the products, the offer, the promise, the proof and the voice. | | [Make static ads](/workflows/make-static-ads) | `POST /v1/workflows/statics` | Turn one product into a set of static ads, with the copy, the brand colours and the logo in the image. | Remix and make-static-ads are the two workflows that run the roasOS agent. Each answers with an agent run, not with a job. ## Two more pages in this group Neither page below is an eighth workflow. | Page | Path | What it does | | -------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------- | | [Recast an actor](/workflows/recast-an-actor) | `POST /v1/workflows/recast` | The person-swap recipe over the recast door. It adds no path. | | [Research competitor ads](/workflows/research-ads) | `POST /v1/research/jobs` | Find the ads that a company runs on Facebook, in one normalized shape. | Research is its own job family. It has its own read path, `GET /v1/research/jobs/{id}`, and its own status words. Refer to [Research competitor ads](/workflows/research-ads). ## Every workflow is quote-first The three rules of a paid request do not change for a workflow. 1. Send an `Idempotency-Key` header. Use 16 to 255 characters. 2. Send `quote_only: true` to read the price. A quote is free. 3. Send the same body again with the returned `quote_id`. Only this step uses credits. Your key needs the `api:write` scope. Refer to [Quotes and credits](/concepts/quotes-and-credits). roasOS rejects a paid workflow call that has no `quote_only` value and no `quote_id`. The rejection occurs before any work starts. An agent therefore cannot spend your credits without showing you a price first. ## Where the result lands The seven workflows use four read paths. | Workflow | Read the run at | | --------------- | -------------------------------------------------------------------------------------------------- | | Analyze | `GET /v1/workflows/analyses/{id}` — an analysis makes no generation, so it has its own read path | | Extract a brand | `GET /v1/workflows/analyses/{id}` — the same path; an extraction is one analysis of kind `website` | | Remix | `GET /v1/agent-runs/{id}` — the agent-run envelope; each render it starts is a job | | Make static ads | `GET /v1/agent-runs/{id}` — the same envelope; each image it starts is a job | | Recast | `GET /v1/jobs/{id}` — the standard job envelope | | Animate a still | `GET /v1/jobs/{id}` — the standard job envelope | | Extend a video | `GET /v1/workflows/extend/{id}` — the continuation job and the joined clip (`merged`) | Recast and animate-a-still are ordinary generations. They accept `webhook_url` and `wait_timeout_seconds`, and they appear in `GET /v1/jobs`. Refer to [Jobs](/concepts/jobs) and to [Webhooks](/concepts/webhooks). Analyze and extract-a-brand have no webhook. Poll `GET /v1/workflows/analyses/{id}/status` instead. ## Media rules Every media URL must be an immutable object on `https://cdn.roasos.com` that your workspace owns. Any other URL returns `400 reference_media_not_workspace_owned`. Put your own files there with `POST /v1/uploads`. Refer to [Reference media and uploads](/concepts/reference-media). Analyze is the one exception. It also reads a Discover creative, because you analyze a competitor's ad to learn from it. Remix reads a Discover creative for the same reason, and only in `discover_item_id`. It refuses one as edit material with `400 discover_source_not_allowed`. Recast, make-static-ads and animate-a-still have no such exception. You may edit and render only media that your workspace owns. Refer to [Media rights](/concepts/media-rights). ## Use a workflow from an agent Each workflow is also an MCP tool on `https://mcp.roasos.com/mcp`. | Tool | Operation | | ------------------------------- | --------------------------------------- | | `roasos_analyze_ad` | Quote or run an ad analysis | | `roasos_get_ad_analysis` | Read one analysis run | | `roasos_get_ad_analysis_status` | Poll one analysis run | | `roasos_get_ad_analysis_result` | Read the finished analysis document | | `roasos_remix_ad` | Quote or run a remix | | `roasos_recast_video` | Quote or run a recast | | `roasos_static_to_video` | Quote or run an animate-a-still | | `roasos_extend_video` | Quote or run a video extend | | `roasos_get_extend_video` | Read one extend run and its joined clip | | `roasos_extract_brand` | Quote or run a brand extraction | | `roasos_statics` | Quote or run a set of static ads | An extraction is read with the three analysis tools above, because it writes an analysis run. Refer to [Connect an AI agent (MCP)](/mcp). ## The pack skills A workflow door takes a typed body. A pack skill takes your own words instead. roasOS ships twelve pack skills. | Slug | Name | Typed door | | ------------------------- | ------------------- | ---------------------------- | | `roasos:analyze-ad` | Analyze an ad | — | | `roasos:remix-ad` | Remix an ad | `POST /v1/workflows/remix` | | `roasos:discover-format` | Discover a format | — | | `roasos:localize-ad` | Localize an ad | — | | `roasos:statics-factory` | Make static ads | `POST /v1/workflows/statics` | | `roasos:recast-actor` | Recast the actor | — | | `roasos:street-interview` | Street interview ad | — | | `roasos:clone-static` | Clone a static ad | — | | `roasos:animated-story` | Animated story ad | — | | `roasos:song-ad` | Song ad | — | | `roasos:product-effects` | Product effects | — | | `roasos:tiktok-slideshow` | TikTok slideshow | — | Two slugs also have a typed door, and they do the same work through it. The other ten run through the skill path only. Start a skill run with `POST /v1/skills/{id}/runs`, or with the MCP tool `roasos_run_skill`. Send the slug as the id. Every skill run is an agent run, so read it at `GET /v1/agent-runs/{id}`. Refer to [Skills](/agent/skills) for the full table.