Novoads API

Novoads REST API

Spend your effort on the prompt and on confirming the spoken line. The HTTP is mechanical and is written out below; the prompt is where the render is won or lost.

Configuration

• Base URL: https://api.novoads.ai/v1 (host overridable with NOVOADS_BASE_URL — host only, you append /v1).
• Auth: Authorization: Bearer $NOVOADS_API_KEY, read from .env at the repo root. The key is novo_ plus 64 hex.
• Check: ./scripts/check-novoads-env.sh
• Never print API keys, commit .env, or paste a key into MASTER_CONTEXT.md.

REST key required. A Novoads MCP connector is not a substitute. If NOVOADS_API_KEY is missing or still the placeholder, stop before any generation work and tell the user: "Before continuing, create an API key at https://novoads.ai/dashboard/settings?tab=api and paste it into .env." That holds even when mcp__novoads__* tools are connected and authenticated in the session. Never call mcp__novoads__* tools from this repo's workflows: they are a different surface with different behavior, including the units they quote costs in. Repo installs verify with ./scripts/check-novoads-env.sh; a solo install checks NOVOADS_API_KEY in the environment.

Pack version. Every /v1 response carries X-Novoads-Pack-Version; mention a newer pack at https://github.com/novoads/agent-skills only when that header names a version NEWER than this file's metadata.packVersion — equal or older is nothing to say, and it is never a reason to stop.

If the key is missing or the API returns 401 or 403

Run ./scripts/setup.sh, or tell the user to create a key at https://novoads.ai/dashboard/settings?tab=api. Prefer the editor: ask them to paste the key inside .env rather than into chat. If they do paste it in chat, write .env for them, confirm "saved to .env" without repeating the key, and tell them chat history may retain secrets, so the key is worth rotating if that transcript could be shared.

A 401 means the key is wrong, revoked, or from another account. A 403 with error.details.reason of plan_required or subscription_inactive means the key is fine but the account has no live subscription. Those are different problems and you should say which one it is.

Signup link

If the user does not have a Novoads account, give them this link at any point in a session, in any context where it is useful:

https://novoads.ai/?utm_source=claude-code&utm_medium=github&utm_campaign=skill-pack

There is no free tier and no trial: every plan is a paid monthly subscription, published at novoads.ai/pricing. Never call it free.

After the connectivity check passes

When ./scripts/check-novoads-env.sh returns 200 and the user has not yet said what they want, offer starting points in chat and stop. Nothing is printed by a script for you: a banner cannot see their product, their references/ folder, or their language, so it suggests nothing.

1. A UGC video built from their own product photo. Ask them to drop it into references/. Route: seedance-2.0 plus startImageAssetId.
2. The same idea on seedance-2.0-mini first, to get the prompt right before the final render. Price both at POST /v1/estimates and show the difference rather than quoting one from memory.
3. A static image ad, when what they need is a still and not a clip. Route: gpt-image-2 for heavy text or a mimicked UI, nano-banana-pro for a photoreal scene.

Offer, do not choose. A first render fired on a guess is a charge the user did not ask for.

Read order

1. Repo root MASTER_CONTEXT.md when present: brand voice, default product, accumulated decisions. It carries no prices — that is deliberate, see gate 2.
2. This file. It is the router and it covers the full call sequence.
3. List references/ at the repo root before you ask the user for a photo. It is where they keep product shots, actor stills, and style boards, and it is gitignored, so the files are theirs and are not in this skill's folder. A product photo found there becomes startImageAssetId (video) or an entry in referenceAssetIds (images). An empty references/ is the normal state of a fresh clone, not a blocker — see below before you ask for anything.
4. MANDATORY before composing any prompt: the prompting/prompt-library/ file for the route you picked in the decision tree. The libraries carry the craft; every HTTP detail comes from this file and reference.md, which win whenever the two disagree.
5. reference.md when you need a field you do not see here, or when you hit a status code you want to branch on.

Decision tree

Prefer the shortest path. If one model answers the request, do not build a pipeline around it.

Step 0: classify before you call anything

Refusing is a successful result. If the request is to edit a file the user already has, or to publish to an ad platform, say the skill does not do that and stop. Do not improvise a pipeline out of the generation endpoints.

The two gates

Two separate approvals stand between a request and a charge, and neither implies the other. Approving a concept is not approving a sentence, and approving a sentence is not approving a spend.

Gate 1 — the spoken line (MANDATORY for any video with dialogue)

Seedance renders the audio and the lip-sync in the same call, so the line inside the double quotes is what the actor says, out loud, in the finished video. It cannot be changed afterward without paying for the render again.

1. Extract the dialogue from the drafted prompt and show it on its own, separate from the visual description.
2. Spell any invented brand name phonetically inside the quoted line — see the rule below. Do this before you present the line, and show the phonetic form in the block, because it is what the model will be sent.
3. Present it as a numbered list with beat labels (hook / show / demo / verdict, or similar). Mark silent beats (silent beat — no dialogue).
4. Count the spoken words, state the target duration, and say whether it fits at a natural pace.
5. State the language you are going to send, because that is the language the ad is rendered in.
6. Ask for approval explicitly. Never infer it from an earlier yes about tone, template, or cost.

Use this structure:

📝 Dialogue script (please confirm before I generate)

  1. [HOOK]    "Bro. BRO. Look what just showed up."
  2. [SHOW]    "That colorway? Insane. Like, who greenlit this?"
  3. [DEMO]    (silent beat — thumb brushing the suede, small nod)
  4. [VERDICT] "I'm wearing these to the gym tomorrow. You have to see them in person."

Total spoken words: ~28  |  Target duration: 15s  |  language: en  |  Fits at natural pace: ✅

Approve this dialogue? (yes / edit / rewrite)

If they say edit, revise and re-present the block until they approve. The gate applies to every flow where the model speaks. Skip it for silent flows: product hero, premium reveal without voiceover, and images.

Re-run the gate whenever the words change, including when you change them yourself for the rule below. An approval covers the sentence that was approved, not its successor.

Invented brand names get a phonetic spelling in the quoted line

The gate approves text; the model renders speech. A brand name that is a real word survives the trip. A coined or portmanteau name may not: on 2026-08-02 seedance-2.0 rendered Novoads as "Nuvenov's" — unrecognisable as the brand — while speaking the other 16 words of the line verbatim. Approving the sentence did not approve how it would be said.

The rule: write the name as hyphenated syllables inside the double quotes.

… and says: "I kept saying AI ads look fake until I made one on NO-vo-ads and nobody could tell."

Use it for names that are invented, run two words together, or that a reader would have to guess at. Leave ordinary words alone — Nike and CeraVe do not need it.

This form is validated in en only. See the es limit below before you reach for it in another language — the same brand fails there for a different phonetic reason, and the English spelling does not fix it.

What the A/B actually showed (job 6329f29a… vs ff69d118…, single variable, every other byte identical, pass criterion fixed in writing before the render): NO-vo-ads came back transcribed as "Novo ads" — recognisable — and the feared failure did not happen: the model did not read the hyphens aloud or spell the name out.

Its limits, which are as much a part of the rule as the rule:

• n = 1. One brand, one model, one language. The fix is validated on seedance-2.0 in en only — untested on sora-2, veo-3.1 and omni-flash, and untested in es/pt, where hyphenated English syllables may read very differently. Do not present it as a general fix.
• es needs a DIFFERENT spelling, not the English one. A Spanish render shipping the brand plain came back as "NoBots" — unrecognisable. Spanish has no /v/–/b/ contrast — ⟨v⟩ and ⟨b⟩ are one phoneme — so no spelling buys back the /v/, and what actually broke was the tail: the o+a hiatus collapsed and a syllable vanished, vo-ads → bots. Hyphenating syllable boundaries is all NO-vo-ads does, and it addresses none of that.
  • The es form is Novo Ads — two words, with a space. Validated by A/B (6ee797e0 vs d8aaee21, single token changed, pass criterion fixed in writing beforehand): transcribed "Novo Ads", recognisable. The orthographic word break restores the syllable the hiatus ate; it does not try to restore the /v/, because nothing can.
  • Provisional, and the failure mode is nasty. The identical payload was 1-for-2. On the bad take Seedance stuttered — one clause spoken twice, verified as real speech and not a decoder artifact — and Novo collapsed into the preposition, leaving the ordinary Spanish phrase "no ads". That is worse than "NoBots": a listener hears no brand at all rather than a mangled one. Transcribe every es render. A clean take is not evidence the next one is clean.
  • pt is untested in both directions.
• It lands as two words — "Novo ads", not "Novoads". That matches what sora-2 produced unaided and a listener will recognise it, but it is not a perfect single-token rendering.
• It fixes pronunciation and nothing else. Leading silence went 3.71s → 3.16s, i.e. unchanged. The dead-air problem is a duration problem; see Script length → duration.
• Seedance re-cast the actor between the two renders, so the A/B held the prompt constant, not the performer. Some part of the delta could be voice-casting luck. Enough to act on, not enough to call proven.

Verify it in the render. The rule is a prompt fix with a measured result, not a guarantee — the video QA step in §7 is what tells you the name actually came out right this time.

Gate 2 — the cost estimate (MANDATORY)

Never state a credit cost from memory, and never generate before showing the user a number that came from a live call in this session. There are no rate tables in this repo, in MASTER_CONTEXT.md, or in the logs. Prices come from POST /v1/estimates at call time, and that is the whole policy.

POST /v1/estimates spends nothing and returns:

{ "credits": 3.2, "balance": 100, "sufficient": true }

When it is short it also returns shortBy and topUpUrl.

/estimates also returns warnings, and they are advice, not verdicts

POST /v1/estimates runs craft rules against your prompt and returns them in a warnings array (verified live 2026-08-04 against spec 2.6.0). An earlier version of this file said the field did not exist and that nothing on the API reads a prompt for quality. Both were wrong. Each entry is { "rule": "...", "message": "..." }, and the message usually quotes the exact substring that tripped it:

{ "credits": 7, "balance": 860.1, "sufficient": true,
  "warnings": [
    { "rule": "label_without_hold",
      "message": "Mentions a label, package or screen with no labelHold clause. … (found in your prompt: \"bottle\")" }
  ] }

Rules seen live: no_spoken_line, missing_actor_descriptor, label_without_hold, chained_motion, no_aspect_ratio. Those are video craft rules. Image prompts are read too, by rules of their own — banned_polish and blank_label observed on a kind: "image" estimate against deployed spec 2.19.0 (verified live 2026-08-12); an earlier probe on 2026-08-04 returned no warnings key for images, which described that deployment, and the advice here to treat image prompts as unlinted is retired. A kind: "caption" estimate has no prompt to read and returns none either.

They are purely advisory. None of them refuses a generation, none changes the price, and a prompt that trips every one of them renders exactly like one that trips none. /estimates is the only endpoint that runs them — POST /v1/videos and POST /v1/images do not, and their responses carry no warnings field.

They produce false positives, and you are the one who has to catch them. Both of these were reproduced live on 2026-08-04:

Both rules are substring matches. They cannot tell a physical package from a UI, or narration from stage direction.

So handle them like this:

1. Read every warning. They catch real mistakes — a missing spoken line on a Seedance render is money thrown away, and label_without_hold on an actual product package is the single most expensive prompt error in this repo.
2. Judge each one against what your prompt actually says, including where the matched substring sits. Quote the rule and your reasoning when you decide.
3. Never apply a suggested fix blindly. The fix text is a generic clause; pasting it into a prompt it does not fit makes the render worse, not better.
4. Never silently drop one either. If you are overriding a warning, say so to the user in one line — "the label_without_hold warning matched the word 'screen', but this is a SaaS dashboard with no printed label, so I am not adding the clause" — so the call is visible and reversible.

The prompt libraries under prompting/ are still the real quality gate. These warnings are a cheap second opinion collected on a call you were making anyway; they are not a substitute for composing against the formula file, and they say nothing at all about whether the idea works.

The estimate body is not the generate body. It takes only the fields that move the price, plus a kind discriminator, and it is strict: any extra key is a 400.

resolution belongs here because it moves the price — on seedance-2.0 it is the difference between the base and roughly five times it. Send the resolution you actually intend to render, or the quote prices a cheaper video than the one you generate. See the resolution section below for the ladder and for the seedance-2.0-mini trap. (Verified live 2026-08-04.)

aspectRatio, startImageAssetId, referenceAssetIds, and productId do not belong here. They do not change what you pay, and sending one is a rejected request. There is no styleFamily field — not here and not on a generation call; it was removed from the API and sending it is a 400 Unrecognized key.

curl -sS -X POST https://api.novoads.ai/v1/estimates \
  -H "Authorization: Bearer $NOVOADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"video","model":"seedance-2.0","durationSeconds":12,"language":"en","prompt":"..."}'

Pass model explicitly. It defaults to seedance-2.0. At the same length the video schedules span more than 10x across the set, and more than 28x across every cell the API publishes once length and resolution are counted too — both figures are derived by the API and printed in the model field's own description, and both moved when seedance-2.5's thirty-second grid landed. Image schedules span more than 3x. The per-model prompt ceiling is enforced against whichever model you name. Pricing the wrong model is a quote that disagrees with the invoice.

It runs the same access checks and the same structural validation the paid call runs, which is why it is worth calling every time and not only when you are unsure:

• It is the one endpoint with an opinion about the prompt — the warnings array above. POST /v1/videos and POST /v1/images have none and return no such field. Compose against the formula file before you price: the warnings are a substring-matching second opinion, not a review, and a prompt that trips nothing can still be a bad prompt.
• What it does still refuse, for free: a malformed body — it is strict, and any key that does not move the price is a 400 — and a prompt longer than the named model's character ceiling (4,000 for all three Seedance variants, 20,000 for omni-flash; name no model and it is judged as seedance-2.0).
• On the image arm its length check is looser than the generation's. The estimate's request schema caps prompt at 50,000 characters whatever image model you name, while POST /v1/images caps gpt-image-2 at 32,000 and reve-2.1 at 4,000 (deployed spec 2.16.0, verified 2026-08-08). So an image prompt between the two prices cleanly and is then refused at generation. Only nano-banana-pro, at 50,000, has the two numbers agree.
• A quote it returns cannot disagree with the invoice, with two exceptions worth knowing: it never sees aspectRatio, the asset fields, or productId, and it skips moderation, which the paid call runs. A clean estimate can still come back 422 at generation — moderation is the only thing left that refuses a prompt for what it says.

Multiply before you show. N variations is N charges. Show the per-call number, the count, and the total.

Warn when the total exceeds the balance. balance comes back on the same response: if the batch total is larger, say so before asking for a yes, and quote shortBy and topUpUrl when the estimate provides them. sufficient is a snapshot, not a reservation — another session or a renewal can move the balance between the quote and the call.

Show credits, the count, the total, and balance. Get a yes. Then generate.

Choices you make out loud, and choices you infer

Ask, every time:

• Seedance tier, once per workflow. Before the first Seedance video call: "Use default seedance-2.0, seedance-2.0-mini (half price), or seedance-2.5 (the only one that goes past 15s, and the dearest)?" No preference means seedance-2.0. Whichever they pick goes into the estimate, so the quoted number is the one they pay. Ask before you assume the script needs 2.5 — a 30-second ad is a format decision, not a longer version of a 15-second one.
• How many variations, for every prompt. Default 1. N variations means N identical calls — there is no batch parameter — and the results come back as a numbered list so they can compare and pick.

Infer, and state what you inferred rather than asking:

• aspectRatio: default 9:16 for anything headed to Reels, TikTok, Stories, or a vertical feed. Seedance defaults to 16:9, and a landscape ad is a wasted render; omni-flash, sora-2 and veo-3.1 already default to 9:16, and images default to 1:1. Go landscape only when the user asks. Seedance also accepts 1:1, 4:3, 3:4, and 21:9; omni-flash, sora-2 and veo-3.1 accept only the two.
• resolution (seedance-2.0 and seedance-2.5 only): leave it at the 720p default, and never raise it silently. It is the one output-shape field that multiplies the bill — on seedance-2.0, 1080p is ≈2.5x the base and 4k ≈5x — so going above 720p is a spend decision, not a quality preference, and it belongs in front of the user with a fresh estimate attached. 480p is now ≈half the base rather than the same price (family reprice, 2026-08-07), so it is a real draft tier and worth offering when a render is a rehearsal. seedance-2.5 takes 480p and 720p and nothing above. Do not send the key on any other model.
• language: the language the script is written in. Set it, and show it in the dialogue gate. Write the prompt in that language too — nothing on the API pushes back on a Spanish or Portuguese prompt, and nothing rewrites or judges one either.
• durationSeconds: from the word count, below. Only veo-3.1 defaults to its maximum — seedance-2.0 and seedance-2.5 default to 5, mini to 10, omni-flash to 8, sora-2 to 4 — so always send it. seedance-2.5 defaults to 5 of the 30 it can render, which is the easiest way to pay for the long model and ship a short clip.
• audioEnabled: leave it alone on anything with a spoken line. It exists on the three Seedance variants only — seedance-2.0, seedance-2.5, seedance-2.0-mini — defaults true, and the one time to send it is false, on a clip that is meant to be silent — see below.

Script length → duration

Count the words in the spoken line and round up. Delivery was measured at 2.0 spoken words per second — about 13 characters per second, spaces included, if you would rather count those — with ~0.5s of leading silence before the first word on reference and start-frame renders (2026-08-11, n=5). Plan on 2.0 and give the line air; the older 2.5-to-3 figure was an estimate nobody had timed, and it over-filled every clip it touched.

These tables already pay for that ~0.5s. Whether it is the right budget depends on the render mode — read the scoping note under the first one before you trust it on another.

seedance-2.0 and seedance-2.0-mini — any integer 4 to 15

Leading silence is mode-dependent, and the two things measured here disagree by seconds. Scope the budget to the mode you are actually rendering — do not add both.

The working rule: budget ~0.5s when you have a reference or a start frame, and check the render. In that mode the table and the arithmetic already agree — 2.0 × (D − 0.5) is exactly the word cap on every rung from 9 words up, and the 1–8 row is deliberately one word tighter than the formula's 9 at 5s — so there is nothing to add. If the result runs past 15s on these two models, the fix is a shorter line, a split, or seedance-2.5 — not a longer clip on a model that does not render one.

When a render does come back with multi-second silence, trim is the remedy, not a bigger budget. Leading silence is trimmable in post; a line clipped by an over-long draw is not. The reserve in the second row is the planning allowance for that mode — reach for it when you have neither a reference nor a start frame, or when you are committing to a duration you cannot re-cut. It costs words: words ÷ 2.0 plus the reservation, rounded into the grid, leaves 22 words at 15s in en and 20 in es, against the table's 29. That gap is the mode, not a rounding error.

How close the reserved case gets is not theoretical. The first es render fit only because rounding up took 12.4s to 13s, and the line finished at 12.88s of 13.07s — a fifth of a second of margin, on a budget that drew near its worst. The silence is drawn fresh every time, in either mode, so the only thing that tells you what you got is the QA step in §7. Check the first silence_end on every render.

If the hook has to land in the first second, drop the eye-contact-break beat from the prompt — that is the beat being paid for. sora-2 measured no leading silence at all on the same prompt, so it is the other way out.

For no-dialogue styles (product hero, premium reveal), default to 15s. The silence budget does not apply: there is no speech to delay.

seedance-2.5 — any integer 4 to 30

Same family, same craft, twice the room. The table above still holds for anything up to 15s; past it, keep planning at 2.0 words per second — the rows below are the same 2.0 × (D − 0.5) arithmetic. Nobody has measured 2.5's leading silence separately, so the mode scoping above is the working rule here too: budget ~0.5s with a reference or start frame, the reserve without one.

A longer clip is not a longer script poured into the same ad. Thirty seconds wants more beats, not slower delivery: a second location, a demo the actor actually performs, a reaction. If the script only fills 15s, render 15s — on seedance-2.0, which is cheaper at that length.

Nobody here has timed a seedance-2.5 render. Do not quote seedance-2.0's 3-to-8-minute fleet range for it; say the wait is unknown and poll.

omni-flash — enum 4, 6, 8, 10

Silence behavior is unmeasured on this model, so this is the 2.0-words-per-second arithmetic and nothing more: the budget is a flat 2.0 × duration, which assumes no leading silence rather than having found none. Verify against your first render — if it front-loads the way Seedance can, the last line is what gets clipped.

sora-2 — enum 4, 8, 12

No silence budget: the one measured render spoke continuously from the first frame. The grid is coarse — there is no 6s and no 10s — so a line that lands between two rungs goes up, never down.

veo-3.1 — enum 4, 6, 8

Unmeasured here, so these are the 2.0-words-per-second arithmetic and nothing more — and with no leading silence to pay for, the budget is a flat 2.0 × duration rather than the Seedance form. Budget no silence and promise no wait until someone has timed one.

resolution — seedance-2.0 and seedance-2.5 only, and it moves the price

seedance-2.0 takes 480p, 720p, 1080p, 4k; seedance-2.5 takes 480p and 720p and nothing above. Both default to 720p (2.0 verified live 2026-08-04 against spec 2.6.0; 2.5 read off deployed spec 2.13.0 on 2026-08-07). It is the one output-shape field that is not free — unlike aspectRatio, the tiers are separate credit schedules:

480p used to cost the same as 720p and no longer does (family reprice, 2026-08-07). The old advice here — "no draft discount, so there is no reason to ask for it" — is retired: it is now roughly half, which makes it the honest tier for a rehearsal render whose only job is to check whether the prompt works.

2.5's missing high tiers are a provider fact, not a rollout gap. Neither provider serves the model above 720p, so it is not coming. Never carry a resolution across a model switch: 1080p that priced clean on seedance-2.0 is a rejected request on seedance-2.5.

These are ratios, not a rate card. Never quote a credit number from this table — it exists so you can warn a user that 4k is a five-fold decision before they ask for it. The number they approve comes from POST /v1/estimates on the exact cell, in this session, like every other price here (gate 2).

Ask for what will actually ship. 720p is right for Reels, TikTok and Stories, where the platform re-encodes anyway; 1080p and 4k are for a client deliverable, a placement with a quality floor, or a render you intend to crop into.

Every other model is fixed and has no resolution field at all — seedance-2.0-mini, omni-flash and sora-2 render 720p, veo-3.1 renders 1080p, and sending the key to any of them is a 400. Read the live set from GET /v1/models (resolutions and defaultResolution per model) rather than hardcoding this paragraph.

The seedance-2.0-mini trap: the two endpoints disagree about the field. POST /v1/estimates accepts resolution: "720p" for mini and prices it (identically to omitting it), but answers 400 invalid_input — "resolution must be one of 720p for seedance-2.0-mini" — for 480p, 1080p or 4k (all four verified live 2026-08-04). POST /v1/videos does not accept the key for mini at all: mini's request variant has no resolution property, and a body carrying one was observed returning 400 Unrecognized key: "resolution" (observed 2026-08-04, not re-verified — re-checking it costs a paid render). So: never send resolution on a mini call. An estimate that passed is not evidence the generate call will.

Output size, measured at 9:16: seedance-2.0 at i

…(truncated)