kavilo

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:

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.