01 · Overview
What MCP is
MCP (Model Context Protocol) is a standard way for AI clients to call external capabilities. With the kiikii MCP server, you can check credits, clone avatars, generate digital human videos, images, videos and voiceovers directly from Cursor, Claude Desktop or Trae without opening the website.
Quick answers
- One configuration covers both digital human and general creation.
- Non-WorkBuddy clients use a personal API key (starts with
kii_sk_); WorkBuddy uses OAuth. - Digital human video is plan first, confirm later; image, video and audio jobs are asynchronous.
- The full key is shown once; up to 10 active keys, each with its own configuration.
One kiikii MCP configuration already contains both digital human and general creation tools. The model chooses the right tool based on whether an avatar or a cloned voice needs to appear.
02 · Capabilities
What you can do
| Capability | Details | Example prompt |
|---|---|---|
| Account | Credits, plan and recharge link | Check my kiikii credit balance |
| Avatars | Clone from portraits, design a new avatar, list avatars | Clone my avatar from this photo |
| Voices | System voices, cloned voices, match by gender and age | Find a warm female voice around 45 |
| Digital human video | Five modes, shot plans, confirm, revise, subtitles | Make a 45-second explainer about chrysanthemums |
| Images | Text-to-image, reference images, 1–4 per call, up to 4K | Generate a 4K 16:9 coffee poster |
| Video | Text-to-video, image-to-video, first/last frame, references, audio driven | A 5-second rainy neon street clip |
| Voiceover | Text-to-speech with voice, speed, format and tone | Read this script in a male Chinese voice |
| Assets and jobs | Upload tickets, gallery link, job status and results | Send me the video you just generated |
When a mode, avatar, voice or duration is unclear, the assistant asks first or returns options instead of producing a video that misses the point.
03 · API Key
Create an API key
A key is the identity of your MCP connection. It can spend your credits, so treat it like a password.
Open the key page
Sign in and go to Profile → API keys, or open /profile?section=apiKeys.
Create a key
Name it after the client or teammate (for example WorkBuddy-1 or Cursor-office) and choose an expiry. One key per client is recommended.
Copy the full configuration
The creation dialog shows the full key and a ready-to-use MCP config. Copy it immediately; the key cannot be viewed again.
Revoke when needed
Revoke any key from the list. It stops working immediately and does not affect other keys.
| Item | Details |
|---|---|
| Format | Starts with kii_sk_, shown once, only a hash is stored |
| Limit | Up to 10 active keys for different clients or teammates |
| Scopes | Account read, assets read, assets write; no admin access |
| Expiry | Never / 30 / 90 / 365 days, expires automatically |
| WorkBuddy | Uses OAuth and does not need this key |
Never commit a key to a public repository, screenshot it or paste it into a group chat. Create separate keys per person so access can be audited and revoked individually.
04 · Connect
Connect a client
The kiikii MCP server uses Streamable HTTP, so there is nothing to install locally.
Generic MCP configuration
{
"mcpServers": {
"kiikii": {
"type": "streamableHttp",
"url": "https://api.kiikii.vip/api/mcp",
"headers": {
"Authorization": "Bearer <your API key>"
}
}
}
}| Client | Where to configure | Notes |
|---|---|---|
| Cursor | ~/.cursor/mcp.json | Merge the mcpServers block and restart Cursor |
| Claude Desktop | claude_desktop_config.json | Merge the block and restart the app |
| Trae | Settings → MCP → Add | Choose HTTP / Streamable HTTP, add the URL and an Authorization header |
| WorkBuddy | Connector install | OAuth authorization, no API key needed |
Paste the config
Merge the mcpServers block into your client. Separate keys can use different server names such as kiikii-work and kiikii-home.
Restart the client
Quit completely and reopen so the MCP server is loaded.
Verify
Ask “Check my kiikii credit balance”. A nickname and balance means the key and network are working.
If the client returns 401, check that Authorization is Bearer plus the full key, and that the key is neither revoked nor expired. Never put a key in a URL parameter.
05 · Tools
Tool reference
You do not need to memorize tool names; the assistant picks them. Use this table to understand why a tool was called.
| Tool | Purpose | When it is used |
|---|---|---|
| kiikii_get_account | Nickname, credits, plan, recharge link | Before generating |
| kiikii_list_modes | Five digital human modes and a recommendation | When the mode is unclear |
| kiikii_list_avatars | List usable avatars with avatarId | Before digital human video |
| kiikii_create_avatar | Clone or design an avatar (async) | When a new avatar is needed |
| kiikii_list_voices | Filter voices by gender, age and keywords | Choosing a voice |
| kiikii_create_voice_clone | Clone a voice from a sample | When a custom voice is needed |
| kiikii_create_upload_ticket | Create an upload ticket and URL | Uploading images, audio or songs |
| kiikii_complete_upload | Validate and register the file, return assetToken | After the bytes are uploaded |
| kiikii_get_upload_ticket | Check upload ticket status | Recovering an interrupted upload |
| kiikii_create_video | Create a plan only, no production | Starting a digital human video |
| kiikii_confirm_video | Confirm the plan and start production | Only after explicit confirmation |
| kiikii_revise_video_plan | Revise the plan on the same job | Changes before confirmation |
| kiikii_update_video_subtitles | Re-burn subtitles without regenerating frames | Subtitle changes after the final cut |
| kiikii_get_job | Avatar and video job status and results | Plan, progress, final video |
| kiikii_list_jobs | Recent jobs | When a jobId is missing |
| kiikii_generate_image | Text-to-image and reference images | Posters, covers, illustrations |
| kiikii_generate_video | Text-to-video, image-to-video, first/last frame, audio driven | Scenes without an avatar |
| kiikii_generate_audio | Text-to-speech | Narration and voiceover |
| kiikii_get_creation | Creation job status and results | Polling image, video and audio jobs |
| kiikii_list_creation_models | Available image, video and audio models | Model choice or parameter limits |
| kiikii_open_asset_gallery | Signed asset gallery link | Browsing avatars or voices |
06 · Digital Human
Digital human video
Digital human videos follow plan → confirm → produce, so you never pay for a film that went in the wrong direction.
| Mode | Best for | Target duration | Inputs |
|---|---|---|---|
| studio | Explainers, courses, product intros | 30–150 s | Avatar + voice |
| continuous | Single-take talking head | 20–60 s | Avatar + voice; slower to render |
| mv | Songs, covers, brand themes | Follows the song | 1–2 avatars + a song |
| ecommerce | Product selling points and promos | 20–80 s | Avatar + voice + product image (+ scene image) |
| store_visit | Local stores and tourism | 20–80 s | Avatar + voice + 1–3 scene images |
Create a plan
kiikii_create_video only returns shots and script. If mode, avatar, voice or assets are missing, it asks first.
Review and confirm
The assistant must show the plan, duration and estimated credits, then wait for an explicit yes before kiikii_confirm_video.
Revise on the same job
Say “change shot 2 to text-to-video” or “make shot 3 more conversational”; kiikii_revise_video_plan edits the original job.
Produce and fetch
Production is asynchronous; use kiikii_get_job for stage and final video. A failed segment can be retried alone.
Example prompt
Use my avatar "Zhiya" and a warm 45-year-old female voice. Make a 45-second explainer about chrysanthemums and the Double Ninth Festival: hook, varieties, symbolism and customs, ending with one care tip. 9:16, 720p, burned-in subtitles. (After the plan) Change shot 2 to a text-to-video insert of chrysanthemums after rain; change shot 3 to a web animation timeline.
Continuous mode takes noticeably longer. MV supports only 480p / 720p. Avatar, voice, aspect ratio and resolution are project settings and must be changed in the workbench.
07 · Creation
Images, video and voice
For assets that do not need an avatar, use the general creation tools; each call returns a jobId.
Images
- Up to 4 images per call, billed individually; text-to-image and reference images (up to 4) are supported.
- Ratios: auto / 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3.
- Resolution: 1K / 2K / 4K; only nano-banana-2 truly supports 2K and 4K. Other models are submitted at 1K.
- When the user names a model, call kiikii_list_creation_models and use the returned model value.
Video
- Text-to-video, image-to-video, first frame, first/last frame, reference image/video and audio driven; one clip per call.
- Ratios: auto / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16; resolution 480 / 720 / 1080; default 5 seconds.
- If the clip needs an avatar, talking head, lip sync or a singing MV, use the digital human tools instead.
Voice
- Up to 20,000 characters, with format and speed (0.5–2).
- Describe the voice with voiceHint or gender + age; the server matches the closest real voice by age and character.
- Use kiikii_create_voice_clone first when you need a unique voice.
General creation shares model routing, concurrency and credit rules with the web app. Unsupported ratios or resolutions are clamped to the supported range rather than failing silently.
08 · Jobs & Credits
Jobs and credits
Every generation is asynchronous: the create call returns a jobId, and the result is fetched by a query tool.
| Job type | Create with | Query with | Result |
|---|---|---|---|
| Avatar | kiikii_create_avatar | kiikii_get_job | Avatar ID, four-view sheet and cover |
| Digital human video | kiikii_create_video / confirm_video | kiikii_get_job | Plan, segment status, final video URL |
| Image | kiikii_generate_image | kiikii_get_creation | Image URLs, model, actual cost |
| Video | kiikii_generate_video | kiikii_get_creation | Video URL, model, actual cost |
| Voiceover | kiikii_generate_audio | kiikii_get_creation | Audio URL, voice, actual cost |
- Poll every 10–20 seconds and stop once the job succeeds or fails.
- Call kiikii_get_account before generating; results include the actual cost.
- Failed jobs are refunded per site policy. Timed-out jobs stay running; keep querying the same jobId without creating a duplicate.
- Digital human video accepts an idempotencyKey; reuse it when retrying to avoid duplicate projects.
Credit rules match the web app: images per image, video by duration and resolution, voiceover by text length. See “Models & credits” for unit prices.
09 · Tips
Tips
Clear requests and specific revisions produce far more stable results.
Ask for a mode first
If unsure, describe the goal and duration and let the assistant recommend a mode instead of forcing continuous.
Change one thing at a time
Name the shot and the target change; up to 3 shots per revision. Do not change avatar, voice and visuals in one sentence.
Shot types are editable
Studio plans mix web animation and image scenes by default. Ask to change shot 2 to text-to-video for a live-action insert, or shot 3 to a digital human long take.
Upload before referencing
Assets cannot be replaced mid-conversation. Upload first and use the assetToken; on the web, upload in the asset center and replan.
Describe voices
“45-year-old female, warm and intellectual” works better than guessing an ID; the result includes the matched voice and a note.
Separate post-production edits
Subtitle style uses subtitle re-burn, visual or script changes need a plan edit, and “re-assemble the final cut” only rebuilds the final video.
If the assistant asks for more detail, answer with the shot number, target type or reference asset. It asks to save credits rather than guessing.
10 · FAQ
FAQ
The questions that come up most often when connecting for the first time.
How is MCP different from the WorkBuddy connector?
Both expose the same kiikii capabilities. WorkBuddy installs a connector through OAuth and needs no API key; Cursor, Claude Desktop and Trae use a personal API key. A key and a connector can be used at the same time.
Why are my MCP images only 1K?
Only nano-banana-2 supports 2K and 4K right now; every other image model is submitted at 1K. Call kiikii_list_creation_models first, then pass resolution: 1K / 2K / 4K to kiikii_generate_image.
Why did a revision create a new video instead of changing the plan?
Digital human video uses a two-phase flow: kiikii_create_video only produces a plan, and production starts after explicit confirmation. When a plan is already awaiting confirmation, use kiikii_revise_video_plan on the same job.
A job stays in progress for a long time. What should I do?
Image, video and audio jobs are asynchronous. Poll every 10–20 seconds with the returned jobId; do not poll continuously. A timeout does not charge twice; always read the actual cost from the result.
Can I recover a lost API key?
No. The full key is shown only once at creation and the server stores only a hash. Copy the ready-to-use MCP config immediately. If it is lost, revoke the key and create a new one.
How many keys can one account create?
Up to 10 active keys. Each key corresponds to its own MCP configuration, so you can separate clients or teammates. Revoking one key does not affect the others.
How do uploads work over MCP?
Call kiikii_create_upload_ticket to get an upload URL, PUT the file bytes to it, then call kiikii_complete_upload to obtain an assetToken. Later tools only accept assetToken values, not local file paths.
Do MCP generations consume credits?
Yes. MCP uses the same credit rules as the web app and deducts from the same balance; failed jobs are refunded according to site policy. Call kiikii_get_account before generating.
11 · Get Started
Get started in three steps
One key, one config block, one balance check.
Create a key
Open Profile → API keys and copy the ready-to-use MCP config.
Paste it into your client
Merge mcpServers into Cursor, Claude Desktop or Trae, then restart.
Verify and create
Ask “Check my kiikii credit balance”, then “Make a 45-second explainer with my avatar”.