| name | kavilo |
| description | Generate AI images and videos with Kavilo Creative AI using the user's own account and credits, via Kavilo's remote MCP server. Use when the user asks to create, iterate on, or animate product images, marketing visuals, posters, or short videos with Kavilo — or mentions connecting their agent to Kavilo. Covers connecting the MCP server (OAuth, no API keys), the quote → confirm billing flow, chained image-to-video workflows, cost strategy, and prompt guidance for the gpt-image-2 and Seedance models. |
Kavilo Creative AI
Kavilo generates images (gpt-image-2) and videos (Seedance sd2 family) through a
remote MCP server. Generations run on the user's Kavilo account and spend their
prepaid credits, so this skill's most important rule is: nothing is generated
or charged without the user's explicit approval of a quote.
Always converse in the user's language; this document is in English only for
the model's benefit.
Setup — connect the MCP server first
Check whether the Kavilo MCP tools (generate_image, generate_video,
confirm_generation, get_generation, get_credit_balance) are available in
this session. If they are, skip this section.
If they are not available:
-
In Claude Code, offer to register the server (ask before running it):
claude mcp add --transport http kavilo https://www.kavilocreativeai.app/api/mcp
-
Tell the user to run /mcp, select kavilo, and choose Authenticate.
A browser window opens for OAuth sign-in — no API keys are involved.
-
The tools appear in the session after authentication (a session restart may
be required). Setup instructions for other clients (claude.ai, Cursor) are
at https://www.kavilocreativeai.app/docs/mcp — the server URL is the same.
The quote → confirm contract
Every generation is two-phase. generate_image / generate_video do NOT
generate anything: they return a quote (quote_id, exact credits, the
normalized parameters, and the account balance). Only confirm_generation
starts the generation and charges credits.
Etiquette you must follow:
- Always present the quote to the user before confirming: show the credit
cost, the parameters that matter (model, resolution, duration, count), and
the remaining balance. Then ask for approval.
- Never call
confirm_generation unless the user explicitly approved that
exact quote. The user_approved: true argument is your attestation of
that approval — do not set it speculatively.
- If the user says something like "go ahead for this whole batch, stop
asking", you may confirm subsequent quotes in that batch without re-asking —
but still surface each quote's cost briefly, and re-ask if the cost profile
changes materially (e.g. jumping from a 5-credit draft to a 570-credit 4K
video).
- Quotes expire after 15 minutes and their parameters are locked. If the
user wants changes, create a new quote instead of arguing with the old one.
- If the quote returns
insufficient_balance, tell the user and point them to
the pricing page to top up before confirming.
- Never repeat pricing tables from memory — the quote's
credits field is the
only authoritative price.
Polling
After confirmation, poll get_generation with the same id every 10–15
seconds. Images usually finish within a minute; videos can take several
minutes, and jobs with reference media go through a provider content review
first (status preparing_references). At most 5 jobs can be in progress
per account — if you hit the limit, wait for one to finish.
When a job completes you receive download URLs plus compressed inline
previews. Look at the previews: judge composition, subject accuracy, and
style before declaring success, and propose a refined prompt if the result
misses the brief.
Core workflows
Draft cheap, finalize high. Iterate at the cheapest tier (images:
medium quality / 1k; videos: sd2-mini / 480p or 720p, short
duration). Only re-run the winning prompt at high quality / resolution for
the final deliverable. Say this plan out loud so the user knows why the first
results are drafts.
Image → video chaining. Any completed image generation can seed a video:
pass its generation_id as first_frame_image in generate_video
(image-to-video), or as a reference_images entry. This is the standard
"generate a product shot, then animate it" flow — no file handling needed.
Keyframe interpolation. Provide both first_frame_image and
last_frame_image (two generation_ids or URLs) to interpolate between two
states — good for before/after reveals and transformations.
Reference-guided video. reference_images / reference_videos steer
style and motion (omni-reference mode; cannot be combined with first/last
frame). URL-based reference videos require an accurate duration_seconds
(max 15s) because it affects pricing. All references pass provider content
review before generation; rejected references fail the job without charging.
Campaign sets. For multi-placement campaigns, run the approved prompt
across aspect ratios (1:1, 16:9, 9:16) as separate quotes, and use
count (up to 4) for in-ratio variations.
Prompt writing guidance (load only when composing prompts):
Troubleshooting
- Quote expired — create a new quote; parameters cannot be edited in place.
- "Not enough credits" — check
get_credit_balance, then send the user to
the billing page to top up. New accounts get welcome credits on first use.
- Reference rejected by content review — the job fails with the review
reason and nothing is charged. Suggest a different reference asset.
- Concurrency limit reached — the error lists the active job ids; poll one
of them and resubmit after it finishes.
- Results in the product UI — everything your agent generates also appears
in the user's Kavilo workspace under the "Quick Create" project, where they
can keep editing and reusing it.
