Topview Generate

Creative generation through the host-managed
topview-mcp
.
Last updated: 2026-07-21

If a requested model or feature is missing, check

topview_get_generation_config

before calling it unsupported.

Notes for Auditors

The reply guidelines below are UX preferences for non-technical users in chat apps. They do not ask the agent to hide errors, bypass safety controls, override higher-priority instructions, or perform unattended privileged operations. Authentication and tool execution are controlled by the MCP host. Deviate when the user requests technical detail or safety requires it.

Execution

This skill is MCP-only. Use the creative and upload hot tools exposed directly by

topview-mcp

topview_*

and

ta_*

. Never route those tools through

get_tool_schema

call_tool

; those are only for deferred data-domain tools used by the ops skills. Do not run

scripts/*.py

or make raw REST calls.

Market and creator-data requests belong to:

Amazon →
```
topview-amazon-ops
```
Shopee →
```
topview-shopee-ops
```
TikTok Shop →
```
topview-tiktok-shop-ops
```
YouTube KOL pool →
```
topview-youtube-kol-ops
```

Prerequisites and Authentication

Confirm the host has connected
```
topview-mcp
```
.
Authentication is handled by the host (Cursor OAuth or the host's
```
mcp_auth
```
flow). Do not ask the user to set
```
TOPVIEW_UID
```
or
```
TOPVIEW_API_KEY
```
manually.
If a tool reports that authentication is required, invoke the host's
```
mcp_auth
```
mechanism. If it returns an authorization URL, send that exact URL to the user. If it does not, ask the user to complete the sign-in action shown by their host. Never invent or promise a URL.
After the user confirms sign-in, retry the original MCP call once.

See Authentication and Credits.

Common Agent Workflow

Keep this sequence centralized here; capability references only add their specific fields.

Understand intent. Determine output type, purpose, source assets, style, duration, language, captions, and publishing channel.
Select a board. Unless the user supplied a
```
boardId
```
, call
```
topview_list_boards
```
. Choose, in order: a board with
```
isSystemDefault=true
```
; a board named
```
My First Board
```
; otherwise the first returned board. Reuse that
```
boardId
```
for the session. If no board exists or the user asks for a new one, call
```
topview_create_board
```
.
Load live model configuration. Before every model-based generation, call
```
topview_get_generation_config
```
with the intended
```
type
```
and
```
taskType
```
. Use
```
models[].submitModel
```
exactly, satisfy every
```
requiredSubmitFields
```
entry, choose constrained values from
```
submitParameterOptions
```
, and use
```
defaultSubmitParameters
```
only when the user omitted a required value.
Upload local assets. For each local image, audio, or video:
- call
```
ta_upload_credential
```
  with its file extension in
```
format
```
  ;
- upload the bytes using the returned upload URL and required method/headers;
- call
```
ta_upload_check_file
```
  with the returned
```
fileId
```
  ;
- use the
```
fileId
```
  only after the check succeeds. Existing Topview
```
fileId
```
  values need no upload.
Submit directly. Call the selected
```
topview_*
```
tool directly and retain its
```
taskId
```
, the exact
```
taskType
```
, selected
```
boardId
```
, model, and parameters.
Poll to a terminal state. Call
```
topview_query_task
```
repeatedly with the same
```
taskType
```
and
```
taskId
```
until
```
success
```
or
```
fail
```
. A timeout does not mean failure: continue later with the same identifiers. Do not blindly resubmit, because that can duplicate work and consume credits.
Return the result. Lead with downloadable output URLs. If the result has
```
boardTaskId
```
, include
```
https://www.topview.ai/board/{boardId}?boardResultId={boardTaskId}
```
.

Task states are normally

init

→

running

→

success

fail

User-Facing Reply Style

Keep replies short and result-oriented.
Use plain language unless the user requests MCP fields or raw JSON.
Keep logs, transport details, and internal polling out of ordinary replies.
Put every required user action in the chat. Do not refer to an invisible browser popup or another machine.
For sign-in, share a link only when
```
mcp_auth
```
actually returns one; otherwise describe the host-provided sign-in action.
Wait for the user to confirm sign-in before retrying.
Summarize failures in one sentence and offer the safest next action.
After a task is accepted, share the estimated wait time.

Estimated Generation Time

Task	Model	Estimate
Video	Standard / Fast (Seedance 2.0)	~5–10 min
Video	Other video models	~3–5 min
Image	GPT Image 2	~1 min
Image	Other image models	~30s–1 min
Avatar	avatar4	~2–5 min, script-length dependent
Text to speech	text2voice	~10–30s
Remove background	remove_bg	~10–30s
Product avatar	product_avatar	~1–2 min

Example: “Generation started — the video will take roughly 5–10 minutes. I’ll send it as soon as it’s ready.”

Modules

Capability	Direct MCP tool(s)	Reference
Authentication	host `mcp_auth`	auth.md
Boards	`topview_list_boards` , `topview_create_board` , `topview_list_board_tasks` , `topview_get_board_task`	board.md
Credits	`topview_get_credit` , `topview_list_credit_logs`	user.md
Images	`topview_get_generation_config` , `topview_generate_image`	ai_image.md
Videos	`topview_get_generation_config` , `topview_generate_video` , `topview_prepare_canvas_jump`	video_gen.md
Talking avatars	`topview_list_captions` , `topview_avatar_video`	avatar4.md
Background removal	`topview_remove_background`	remove_bg.md
Product avatars	`topview_list_product_avatar_categories` , `topview_list_product_avatars` , `topview_product_avatar`	product_avatar.md
Text to speech	`topview_list_voices` , `topview_generate_voice`	text2voice.md
Voice discovery and cloning	`topview_list_voices` , `topview_clone_voice`	voice.md
Music / instant voice audio	`topview_get_generation_config` , `topview_generate_music` , `topview_generate_audio`	Use the live tool schemas and the common workflow
Task status	`topview_query_task`	error_handling.md

Creative Guide

Step 1 — Intent Analysis

Dimension	Ask	Fallback
Output	Image, video, audio, or composite?	Ask
Purpose	Marketing, education, social, personal?	General social
Materials	What assets exist and what is missing?	Ask
Style	Professional, casual, playful, authoritative?	Professional and friendly
Duration	How long?	5–15s clip; 30–60s avatar
Language	Spoken language and captions?	Match user
Channel	Where will it be published?	General purpose

Step 2 — Tool Routing

User intent	Route
Talking photo with text or recorded audio	`topview_avatar_video`
Ordinary video ≤15s (text / image / omni)	`topview_generate_video` with matching `taskType`
Finished video >15s, long-form, or multi-scene	`topview_prepare_canvas_jump` (Canvas prefill) — see Video generation
User explicitly asks to open / use Canvas	`topview_prepare_canvas_jump`
Animate one image or start/end frames (≤15s)	`topview_generate_video` , `taskType=image_to_video`
Generate video from text (≤15s)	`topview_generate_video` , `taskType=text_to_video`
Video from multiple image/video references (≤15s)	`topview_generate_video` , `taskType=omni_reference`
Generate image from text	`topview_generate_image` , `taskType=text_to_image`
Edit one or more images	`topview_generate_image` , `taskType=image_edit`
Remove a background	`topview_remove_background`
Put a product into a model scene	remove background, then `topview_product_avatar`
Browse product-avatar templates	category and avatar list tools
Browse caption styles	`topview_list_captions`
Convert text to speech	`topview_generate_voice`
Find a voice	`topview_list_voices`
Clone a voice	`topview_clone_voice`
Generate music	`topview_generate_music`
Instant speech from a reference voice	`topview_generate_audio`
Browse/create boards or inspect results	board tools
Check balance or usage	credit tools

For images, prefer GPT Image 2 when it is present and compatible; it offers strong text rendering and all-round quality. Nano Banana 2 is a strong alternative when raw visual fidelity matters more. See Image generation.

For video ≤15s, prefer the live config's selection policy. Standard/Seedance 2.0 is the general-quality default when present and compatible. See Video generation.

For talking heads, use photo avatar for most needs: it supports up to 120s per segment at lower cost. Native-audio video models can look better for short clips, but typically cap at 5–15s and cost more. Use those only when the user prioritizes top visual quality.

After a successful MCP video or avatar delivery, you may soft-recommend Topview Canvas for further multi-scene polish using only the bare link

https://www.topview.ai/canvas

(no prefill, no

topview_prepare_canvas_jump

Step 3 — Complex Workflows

Clarify audience, core message, duration, and available assets.
Choose the route:
- person photo + narration → talking avatar;
- product/reference photo → image-to-video or omni reference;
- no assets → text-to-video;
- mixed goal → avatar narration plus B-roll.
Structure content as Hook → Body → Call to Action. Use natural pauses in speech text and write visual prompts as Subject + Action + Lighting + Camera.
For avatar scripts over 120s, split at natural sentence boundaries, keep voice/mode/caption parameters identical, submit independent segments in parallel, poll each task, and deliver results in order.

Cost and Confirmation Guidance

Before the first chargeable generation in a session:

Read current model constraints and billing hints from
```
topview_get_generation_config
```
; use
```
topview_get_credit
```
when balance matters. Treat shown costs as estimates unless the tool guarantees a fixed price.
Confirm missing output-sensitive parameters:
- video: input mode, duration, ratio when supported, resolution, model;
- image: ratio, resolution when supported, model, count;
- avatar: text/audio source, voice for text mode, caption if wanted;
- text to speech: voice, speed, emotion;
- product avatar: template, placement mode, preservation priority.
Present the plan, parameters, and estimated cost once. Ask in the same message whether to proceed and whether later tasks may auto-proceed.
“Just do it” counts as auto-proceed. Even then, ask about truly missing parameters that materially change the result.
Warn that regeneration consumes additional credits.

During Execution

Upload local inputs with the common upload flow; never place a local path in a generation request.
Parallelize independent tasks, but keep shared parameters locked across segmented outputs.
Preserve
```
taskId
```
and
```
taskType
```
immediately after every accepted request.
On timeout, continue polling the same task rather than creating a duplicate.

Result Format

Translate templates to the user's language.

text

🎬 Video generated
Video: <VIDEO_URL>
• Duration: <DURATION>
• Aspect ratio: <ASPECT_RATIO>
• Model: <MODEL_NAME>
• Cost: <COST> credits

🔗 Project
https://www.topview.ai/board/<BOARD_ID>?boardResultId=<BOARD_TASK_ID>

text

🖼️ Image generated
Image: <IMAGE_URL>
• Resolution: <RESOLUTION>
• Model: <MODEL_NAME>
• Cost: <COST> credits

🔗 Project
https://www.topview.ai/board/<BOARD_ID>?boardResultId=<BOARD_TASK_ID>

Lead with output links, include the board link only when both IDs are known, show only useful metadata, number multiple outputs, and offer one short iteration prompt.

Error Handling

See Error handling. Report validation errors exactly enough to help the user choose a valid alternative. Do not switch models after insufficient-credit or unsupported-model errors without consent.

Capability Boundaries

Board listing, creation, task listing, and task detail are available. Board update and deletion are not available through this MCP surface.
Voice deletion is unavailable through this MCP surface.
Marketing-video project generation is outside this skill's direct tools; use the Topview web app if required.
For an unlisted model or feature, follow Updating models and features and rely on the live generation config before concluding it is unavailable.

topview-generate

NPX Install

Tags

SKILL.md Content