circ

Review Ad

A page a HUMAN can look at: the cut, the scenes it was built from (hook / problem / demo / CTA), and the gate verdicts. Show them the url - do NOT read the video yourself. Works from the moment a job is ordered; the scenes are reviewable before the render is. Returns the scene list so you can act on 'the second one is wrong' without watching anything: the way to change it is regen(job_id, note), naming the scene in the note.

Edit Plan

Open a DRAFT plan in the editor, before anything is spent: the human retimes scenes, reorders them, rewrites the lines, then prices and orders from inside the widget. Use this on a draft (remix_ad's output, or a plan you just wrote) - not on a job that already rendered, which is review_ad plus regen. Nothing is stored and nothing is charged; the edited plan comes back through quote_ad / order_ad like any other. This is the revise step for hosts that render

Balance

FREE. What the account can spend, and what an ad costs against it, with no plan needed. Returns the prepaid credit balance, the per-second rate at each resolution, the cost of a 30s ad, how many such ads the balance covers, and whether the free first ad and the free regen are still available. Call this before promising the user anything about cost, and to find out whether the next regen is free or a full-price paid generation. Reads only: generates

Quote Ad

FREE. What circ intends to make, and what making it costs. Nothing is generated. Returns `plan`: the concept, why that direction, the hook, the full spoken script, a scene-by-scene treatment, duration, format and price. SHOW `plan` to the user and ask "anything you want changed, or should I make it?" before you call order_ad. `plan.delivered` is the file they receive (1080x1920 for 9:16). `plan.generated_at` is the generation tier the price is set by. They

Remix Ad

The door: a PROVEN ad (URL or media link) + your offer or product in; a draft plan with its lineage (teardown), a draft manifest, and a free judged quote out. The quote carries `plan`: concept, hook, full script, scenes and price. SHOW IT and ask whether they want anything changed before ordering. `offer` is whatever is being sold - a product, a service, a signup, a lander URL. It is the affiliate word for it, and an ordinary product description is exactly

Plan Ad

The door when you have an offer or product and no plan: CIRC writes the strategy, not you. `offer` is whatever is being sold - a product, a service, a signup, a lander URL - and plain ordinary language describing it is exactly right. You get back `quote.plan`: the concept, why that direction, the hook, the full script and a scene-by-scene treatment, with the price. SHOW IT to the user and ask whether they want anything changed before you order. The `lock`

Find Angle

The door when you have an offer or product but no idea what to SAY. `offer` is whatever is being sold, described in ordinary language. Reads what buyers actually wrote, and returns angles that survived an evidence gate: each one cites real comments from enough distinct authors and threads that it is a pattern, not one loud person. You supply the subreddits and queries - you know where these buyers talk. FREE and capped, like quote_ad: no video is generated

Order Ad

THIS IS THE PAID ACTION. Queues an approved plan for generation. This tool, and regen after the free one, are the only things here that cost anything. WHAT IT COSTS: exactly the price quote_ad returns for this same plan. BEFORE YOU CALL THIS: the user must have SEEN the creative plan (quote_ad / plan_ad / remix_ad return it as `plan`: concept, hook, full script, scenes, duration, price) and agreed to it. Show the plan, ask "anything you want changed, or

Job Status

Where a job you own has got to. `milestone` is one plain sentence to relay to the user ("Generating scene 3 of 5", "Assembling the edit", "Final quality check"), with `scenes_done`/`scenes_total` behind it. Poll it while a job runs and tell them what is happening rather than going quiet: production takes minutes, not seconds.

Fetch Ad

The deliverable: video path + the full QA receipt (gates, scores, lineage, hashes). Scoped to the ordering identity - the receipt carries your reference ad and offer. Worth calling on a FAILED job too: you get `draft`, the cut our gates rejected, and `failed_gate`, the one that stopped it. Nothing was charged and the draft is yours - judge it yourself, and if it is not usable, regen(job_id, note) naming what you saw. May include `performance_wanted`: circ

Regen

Regenerate with an additive note (absorbed as a learned constraint, never a rewrite). The FIRST regen on an account is free. Every regen after that is a full-price PAID generation on the same terms as order_ad: it debits prepaid credits, refuses if the balance is short, and charges only on pass. Do not assume later regens stay free. Read the receipt before you spend one.

List Ads

Your past ads, newest first — the way back to work you already ordered. Every other tool needs a job_id you were handed once; this is where you find it again. `query` matches the label, the angle, and your own regen notes, so "the food noise one" or "the Tuesday one" both work. Then: regen(job_id, note) to change one, or fetch_ad(job_id) for the deliverable and its receipt.

Report Performance

Tell us what an ad you ordered actually did in market, so the next one is better. Each row is ONE creative, ONE ad account, ONE day: {job_id or video_sha256, platform, ad_account, day: "YYYY-MM-DD", spend_cents, impressions, clicks, conversions, days_active}. Safe to re-post: a day you send twice updates in place rather than double-counting, so just re-send the last week whenever the platform restates it. We store an opaque handle for your ad acco

Whats Working

What the numbers you reported actually say - your ads grouped by creative class (hook type + angle + format), cheapest CPA first. This is the other half of report_performance: you tell circ what one ad did, this tells you what the class does, so the next order is aimed rather than guessed. Classes below the conversion floor are withheld rather than ranked - too little data is not a cheap winner.

Formats

What we deliver for a placement, and where its UI covers the frame. `delivered` is the file the customer receives: canvas, aspect, container, codecs, fps and the platform's own max duration. `safe_zone_fractions` is the band the platform draws its own chrome over, which qa_frames enforces. Known: reels, stories, feed, tiktok, snapchat, youtube_shorts, x, title. `zone_verified` false means the zone is a CONSERVATIVE ESTIMATE that over-reserves on pu