roasOSWorkflows
Popular creative jobs, each as one API call.
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 | POST /v1/workflows/analyze | Break one ad into its structure: the shots, the transcript, the style and the insights. |
| 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 | POST /v1/workflows/recast | Put your own person and your own product into a video that your workspace owns. |
| Animate a still | POST /v1/workflows/static-to-video | Turn one still image into one video. |
| Extend a video | POST /v1/workflows/extend | Continue one video from its last frame and get one longer clip. |
| 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 | 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 | POST /v1/workflows/recast | The person-swap recipe over the recast door. It adds no path. |
| Research competitor 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.
Every workflow is quote-first
The three rules of a paid request do not change for a workflow.
- Send an
Idempotency-Keyheader. Use 16 to 255 characters. - Send
quote_only: trueto read the price. A quote is free. - 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.
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 and to 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.
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.
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).
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 for the full table.