Kavilo

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:

1. In Claude Code, offer to register the server (ask before running it):

   claude mcp add --transport http kavilo https://www.kavilocreativeai.app/api/mcp
   

2. Tell the user to run /mcp, select kavilo, and choose Authenticate. A browser window opens for OAuth sign-in — no API keys are involved.

3. 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):

• Images (gpt-image-2): references/image-prompts.md
• Videos (Seedance sd2): references/video-prompts.md

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.