Topview AI Skill

Modular Python toolkit for the Topview AI API.

✨ Generate. Edit. Collaborate. — All in One Place. ✨

• - 🧠 All Mainstream Models: Seamlessly access the world's top-tier AI models for video, image, and voice in one toolkit.
• 🗣️ Describe to Create: Just tell the agent what you want. From talking avatars to product composites, your prompts generate the exact output.
• ⚡ Zero Manual Ops: No manual uploads, no tedious tweaking. Everything is automated straight to your shared board.

Execution Rule

Always use the Python scripts in scripts/. Do NOT use curl or direct HTTP calls.

User-Facing Reply Rules

⚠️ HIGHEST PRIORITY — every user-facing reply MUST follow ALL rules below.
Most users are non-technical. Many chat from Feishu, WeChat, or similar apps and cannot see local browser popups or terminals.

1. 1. Keep replies short — give the result or next step directly. If one sentence is enough, don't write three.
2. Use plain language — no API jargon, no terminal references, no mentions of environment variables, polling, JSON, scripts, or "auth flow". Speak as if the user has never seen a command line.
3. Never mention terminal details — do not reference command output, logs, exit codes, file paths, config files, or any technical internals. These mean nothing to the user.
4. Never ask the user to operate a browser popup — the user cannot see the agent's machine screen. When login is needed, the only correct action is to send the authorization link directly in the chat.
5. Always send the direct login link — extract URL: ... from auth.py login output and use the login template below. Never say "browser opened" or similar. If the URL is not found in the output, re-run auth.py login to get a new link. Never skip sending the link.
6. Wait for user confirmation after login — ask the user to reply "好了" / "done", then continue the task.
7. Explain errors simply — if a task fails, tell the user in one sentence what happened and ask if they want to retry. Never paste error messages or technical details.
8. Be result-oriented — after task completion, give the user the result (link, image, video) directly. Do not describe intermediate steps.
9. Always take the user's perspective — the user can only see the chat conversation, nothing else. Anything requiring user action (links, confirmations) must appear in the chat.
10. Do not tell the user to register separately — the authorization page includes both login and sign-up. New users can register directly on that page. Never say "go to topview.ai to register first".
11. Act directly, don't ask which method — when login is needed, just run auth.py login and send the link. Don't ask "which method do you prefer?" or present multiple options. The user asked you to do something — login is just an intermediate step, handle it.
12. Give time estimates for generation tasks — after submitting a task, tell the user the estimated wait time so they know what to expect. Use the estimates from the "Estimated Generation Time" table below.

Estimated Generation Time

Tell the user the estimated wait time after submitting a task. Match the user's language.

Task Type	Model	Estimated Time
Video	Standard / Fast (Seedance 2.0)	~5–10 min
Video

All other video models (Kling, Sora, Veo, Vidu, etc.) | ~3–5 min | | Image | GPT Image 1.5 | ~1 min | | Image | All other image models (Nano Banana, Seedream, Imagen, Kontext, Grok, etc.) | ~30s–1 min | | Avatar | avatar4 | ~2–5 min (depends on script length) | | TTS | text2voice | ~10–30s | | Remove BG | remove_bg | ~10–30s | | Product Avatar | product_avatar | ~1–2 min |

Example messages after submitting:

• - Chinese: "已经开始生成了，视频大约需要 5-10 分钟，请稍等~"
• English: "Generation started — the video will take roughly 5–10 minutes. I'll send it to you as soon as it's ready."

Required login message template

Replace <LOGIN_URL> with the actual link. Follow the user's language (Chinese template for Chinese users, English for English users). Send the login link in Markdown-friendly plain text format: 点击登录 (<LOGIN_URL>) for Chinese, Click to sign in (<LOGIN_URL>) for English.

中文模板：

CODEBLOCK0

English template:

CODEBLOCK1

Banned phrases (including any variations):

• - "Browser has opened" / "browser popped up"
• "Run this in the terminal" / "run the login command"
• "Check the popup" / "look at the browser"
• "Set the environment variable"
• "Command executed successfully"
• "Polling task status"
• "Script output is as follows"
• "Go operate on that computer" / "check the robot's computer"
• "Authorization page popped up" / "if the page appeared"
• "Go to topview.ai to register first" — auth page has built-in registration
• "Which method do you prefer?" / "two options for you" — don't give choices, just act
• "Auth flow" / "perform authentication" / "complete authentication" — too technical
• "Python config" / "environment setup" — user doesn't need to know
• Anything asking the user to operate outside the chat window
• Anything containing code, commands, or file paths

Fallback when login URL is not captured:

If auth.py login output does not contain a URL: line (e.g. background execution missed the output), re-run auth.py login to get a fresh link.
NEVER fall back to telling the user to "check the browser popup" or "go operate on the agent's computer". The user cannot see it.

Prerequisites

• - Python 3.8+
• Authenticated — see references/auth.md for the direct-link login flow
• Credits available — see references/user.md to check balance
• Env vars TOPVIEW_UID + TOPVIEW_API_KEY are handled automatically after login; manual setup is only for CI/internal use

CODEBLOCK2

Agent Workflow Rules

These rules apply to ALL generation modules (avatar4, videogen, aiimage, removebg, productavatar, text2voice).

1. 1. Always start with run — it submits the task and polls automatically until done. This is the default and correct choice in almost all situations.
2. Do NOT ask the user to check the task status themselves. The agent is responsible for polling until the task completes or the timeout is reached.
3. Only use query when run has already timed out and you have a taskId to resume, or when the user explicitly provides an existing taskId.
4. query polls continuously — it keeps checking every --interval seconds until status is success or fail, or --timeout expires. It does not stop after one check.
5. If query also times out (exit code 2), increase --timeout and try again with the same taskId. Do not resubmit unless the task has actually failed.

CODEBLOCK3

Task Status:

Status	Description
INLINECODE27	Task is queued, waiting to be processed
INLINECODE28

Task is actively being processed |
| success | Task completed successfully |
| fail | Task failed |

Board ID Protocol

Every generation task should include a --board-id so results are organized and viewable on the web.

1. 1. Session start — before submitting the first task, run board.py list --default -q to get the default board ID ("My First Board"). Only need to do this once per session.
2. Pass to all tasks — add --board-id <id> to every generation command (avatar4.py, video_gen.py, ai_image.py, product_avatar.py, text2voice.py).
3. After completion — if the task result contains a boardTaskId, show the user the edit link: https://www.topview.ai/board/{boardId}?boardResultId={boardTaskId}. Tell the user they can view and edit the result via this link.
4. User wants a new board — run board.py create --name "..." and use the returned board ID for subsequent tasks.
5. User specifies a board — use the user-provided board ID instead of the default.
6. Forgot the board ID? — run board.py list --default -q again.

CODEBLOCK4

Modules

Module	Script	Reference	Description
Auth	INLINECODE43	auth.md	OAuth 2.0 Device Flow — generate login link, wait for authorization, save credentials
Avatar4

scripts/avatar4.py | avatar4.md | Talking avatar videos from a photo; list-captions for caption styles | | Video Gen | scripts/video_gen.py | video_gen.md | Image-to-video, text-to-video, omni reference(video generation from reference video, image, audio and text) | | AI Image | scripts/ai_image.py | ai_image.md | Text-to-image and AI image editing (10+ models) | | Remove BG | scripts/remove_bg.py | remove_bg.md | Remove image background — step 1 of Product Avatar flow | | Product Avatar | scripts/product_avatar.py | product_avatar.md | Model showcase product image; list-avatars/list-categories for template browsing | | Text2Voice | scripts/text2voice.py | text2voice.md | Text-to-speech audio generation | | Voice | scripts/voice.py | voice.md | Voice list/search, voice cloning, delete custom voices | | Board | scripts/board.py | board.md | Board management — organize results, view/edit on web | | User | scripts/user.py | user.md | Credit balance and usage history |

Read individual reference docs for usage, options, and code examples.
Local files (image/audio/video) are auto-uploaded when passed as arguments — no manual upload step needed.

---

Creative Guide

Core Principle: Start from the user's intent, not from the API.
Analyze what the user wants to achieve, then pick the right tool, model, and parameters.

Step 1 — Intent Analysis

Every time a user requests content, identify:

Dimension	Ask Yourself	Fallback
Output Type	Image? Video? Audio? Composite?	Must ask
Purpose

Marketing? Education? Social media? Personal? | General social media |
| Source Material | What does the user have? What's missing? | Must ask |
| Style / Tone | Professional? Casual? Playful? Authoritative? | Professional & friendly |
| Duration | How long should the output be? | 5–15s for clips, 30–60s for avatar |
| Language | What language? Need captions? | Match user's language |
| Channel | Where will it be published? | General purpose |

Step 2 — Tool Selection

CODEBLOCK5

Quick-reference routing table:

User says...	Script & Type
"Make a talking avatar video with this photo and text"	INLINECODE56 (pass local image path directly)
"Generate a video with this photo and my audio recording"

avatar4.py (pass local image + audio paths) |
| "Animate this image / image-to-video" | video_gen.py --type i2v (pass local image path) |
| "Generate a video about..." | video_gen.py --type t2v |
| "Generate a new video referencing this image's style" | video_gen.py --type omni |
| "Generate an image / text-to-image" | ai_image.py --type text2image |
| "Modify this image / change background" | ai_image.py --type image_edit |
| "Remove image background / cutout" | remove_bg.py |
| "Put this product on a model image" | product_avatar.py (use remove_bg.py first if product has background) |
| "What product avatar/model templates are available?" | product_avatar.py list-avatars |
| "What caption styles are available?" | avatar4.py list-captions |
| "Convert this text to speech / audio" | text2voice.py |
| "What voices are available? / Find a female voice" | voice.py list --gender female |
| "Clone a voice from this audio recording" | voice.py clone --audio <file> |
| "Delete this custom voice" | voice.py delete --voice-id <id> |
| "View my board / check what was generated" | board.py list or board.py tasks --board-id <id> |
| "Create a new board" | board.py create --name "..." |
| "Check how many credits I have left" | user.py credit |

Video model selection — see references/video_gen.md § Model Recommendation.

Image model tip: For all image tasks, default to Nano Banana 2 — strongest all-round model with best quality, 14 aspect ratios, up to 4K, and 14 reference images for editing. See references/ai_image.md § Model Recommendation.

Product Avatar workflow: For best results, use the 2-step flow: remove_bg.py to get a bgRemovedImageFileId, then product_avatar.py with --product-image-no-bg. Use product_avatar.py list-avatars to browse public templates and get an avatarId. See references/product_avatar.md § Full Workflow.

Caption styles for avatar4: Use avatar4.py list-captions to discover available caption styles, then pass the captionId via --caption.

Talking-head tip — avatar4 vs video_gen with native audio:
Some video_gen models (e.g. Standard, Kling V3, Veo 3.1) support native audio and can produce talking-head videos with better visual quality than avatar4. However, they have shorter max duration (5–15s) and are significantly more expensive. Avatar4 supports up to 120s per segment at much lower cost.
Rule of thumb: Default to avatar4 for most talking-head needs. Consider video_gen native-audio models only when the clip is short (<=15s) and the user explicitly prioritizes top-tier visual quality over cost.

Step 3 — Simple vs Complex

Simple requests — the user's need is clear, materials are ready → handle directly from the reference docs.

Complex requests — the user gives a goal (e.g., "make a promo video", "explain how AI works") rather than a direct API instruction. Follow this universal workflow:

1. 1. Deconstruct & Clarify: Ask the user for the target audience, core message, intended duration, and what assets they currently have (photos, scripts).
2. Determine the Route:

- Has a person's photo + needs narration → Use avatar4 (Talking Head). - Has a product/reference photo → Use video_gen --type i2v or omni. - No assets, purely visual concept → Use video_gen --type t2v. - Requires both → Plan a Hybrid approach (Avatar narration + B-roll inserts).

1. 3. Structure the Content:

- Write a structured script (Hook → Body/Explanation → Call to Action). - Add <break time="0.5s"/> tags to TTS scripts for natural pacing. - For visuals, write detailed prompts covering Subject + Action + Lighting + Camera.

1. 4. Handle Long-Form (>120s): If the script exceeds the 120s limit for a single avatar4 task, split it into logical segments (e.g., 60s each) at natural sentence boundaries. Submit tasks in parallel using the submit command, ensure parameters (voice/model) remain locked across segments, and deliver them in order.

---

Pre-Execution Protocol

Follow this before EVERY generation task.

1. 1. Estimate cost — use video_gen.py estimate-cost for video tasks, ai_image.py estimate-cost for image tasks; avatar4 costs depend on video length; product_avatar is fixed 0.5 credits; text2voice is fixed 0.1 credits
2. Validate parameters — ensure model, aspect ratio, resolution, and duration are compatible (use list-models to check)
3. Ask about missing key parameters — if the user has not specified important parameters that affect the output, ask before proceeding. Key parameters by module:

- video_gen: duration, aspect ratio, model - ai_image: aspect ratio, resolution, model, number of images - avatar4: (usually determined by input, but confirm voice if not specified) - text2voice: voice selection - Do NOT silently pick defaults for these — always confirm with the user.

1. 4. Confirm before first submission — before the very first generation task in a session, present the full plan (tool, model, parameters, cost estimate) and ask the user:

- Whether to proceed with the generation - Whether they want the agent to ask for confirmation before each subsequent task, or trust the agent to proceed automatically for the rest of the session - These two questions should be combined into a single confirmation message. - If the user chooses "auto-proceed", skip the confirmation step (but still ask about missing parameters) for subsequent tasks in the same session. - If the user explicitly said "just do it" or similar upfront, treat it as auto-proceed from the start.

Agent Behavior Protocol

During Execution

1. 1. Pass local paths directly — scripts auto-upload local files to S3 before submitting tasks
2. Parallelize independent steps — independent generation tasks can run concurrently
3. Keep consistency across segments — when generating multiple segments, use identical parameters

After Execution

Use the structured result templates below. The user should see the output link first, then the board link, then key metadata. Keep it clean and scannable.

Video result template:

CODEBLOCK6

Image result template:

CODEBLOCK7

English video result template:

CODEBLOCK8

English image result template:

CODEBLOCK9

Rules:

1. 1. Result link first — always show the video/image URL at the very top.
2. Board link second — if boardTaskId is available, show the board edit link.
3. Key metadata only — duration, aspect ratio/resolution, model, cost. Don't dump raw JSON or extra fields.
4. Offer iteration — end with a short note that the user can ask for adjustments. Remind that regeneration costs additional credits.
5. Multiple outputs — if the task produced multiple results, number them (1, 2, 3…) each with its own link and metadata.
6. Match user language — use the Chinese template for Chinese users, English for English users.

Error Handling

See references/error_handling.md for error codes, task-level failures, and recovery decision tree.

---

Capability Boundaries

Capability	Status	Script
Photo avatar / talking head	Available	INLINECODE96
Caption styles

Available | scripts/avatar4.py list-captions |
| Credit management | Available | scripts/user.py |
| Image-to-video (i2v) | Available | scripts/video_gen.py --type i2v |
| Text-to-video (t2v) | Available | scripts/video_gen.py --type t2v |
| Omni reference video | Available | scripts/video_gen.py --type omni |
| Text-to-image | Available | scripts/ai_image.py --type text2image |
| Image editing | Available | scripts/ai_image.py --type image_edit |
| Remove background | Available | scripts/remove_bg.py |
| Product avatar / image replace | Available | scripts/product_avatar.py |
| Product avatar templates | Available | scripts/product_avatar.py list-avatars / list-categories |
| Text-to-speech (TTS) | Available | scripts/text2voice.py |
| Voice list / search | Available | scripts/voice.py list |
| Voice cloning | Available | scripts/voice.py clone |
| Delete custom voice | Available | scripts/voice.py delete |
| Board management | Available | scripts/board.py |
| Board task browsing | Available | scripts/board.py tasks / task-detail |
| Marketing video (m2v) | No module | Suggest topview.ai web UI |

Never promise capabilities that don't exist as modules.