TopMediAi-MCP
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TOPMEDIAI_TOKEN | No | Explicit override token for authentication. Must never appear in public files, screenshots, or issue reports. Standard installation clears this override to avoid inheriting old credentials. | |
| TOPMEDIAI_UPLOAD_ROOT | No | Dedicated directory for user-authorized files to upload as reference media. No extra upload switch is required, but uploads require authorization for specific files and a dedicated directory. | |
| TOPMEDIAI_PRODUCTION_GATEWAY_HOST | No | Explicitly enables the legacy gateway. Production uses direct APIs by default; the legacy gateway has limited capabilities. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| start_loginA | Start official website login on this computer and return an opaque login_id. Reuses an active attempt without opening another page. Never returns a token or private handoff link. Keep the turn active: call wait_for_login until saved or a terminal outcome, then verify status/balance and resume the original request. |
| wait_for_loginA | Wait up to 25 seconds for the start_login attempt. waiting means call this tool again with the same login_id; do not end the reply or ask the user to say continue. saved means verify get_service_status/get_balance and resume the original request. Does not open a page, submit generation or retry a paid request. |
| cancel_loginA | Cancel the current start_login attempt only when the user asks to cancel or stop. Does not remove saved credentials, undo completed login, log out the website or cancel paid tasks. |
| get_service_statusA | Check the environment, refreshed credential source, login guidance and whether generation is enabled. A configured token is not proof of a valid backend login. Does not perform a network login or reveal credentials. |
| list_image_modelsA | List the complete Web image model catalog and per-model capabilities, with live price rows in each model.pricing and independent pricing_status. When the user has not specified a model, use the returned default_model_type. Missing prices never hide models; use an exact quote before generation. |
| get_balanceA | Get the configured TopMediai account tp_all entitlements. Membership queries may initialize first-use entitlements. |
| review_generation_planA | Review the complete current creative flow before a new paid submission, using saved account-scoped quotes and submitted request IDs. Deduplicates retries, displays universal credits only, identifies configured high-price models and universal-credit totals strictly greater than 1000. Specialized entitlement costs remain internal for settlement and budgets. Use the latest explicit confirmation mode in this conversation; a new conversation defaults to conditional. Pass a returned confirmed_plan_id only after human approval of that plan here. Queries do not authorize generation or record consent. Expired/missing pending quotes must be renewed even when confirmation is off. |
| upload_reference_imageA | Upload a user-authorized local PNG/JPEG for image-to-image or video first/last frames from the configured dedicated image directory to the original TopMediai upload service. May create a publicly retrievable OSS URL. Removes image metadata, limits size to 5 MiB, verifies login and returns an account-scoped reference_image_id. Upload requires a configured dedicated directory. Does not generate or debit credits; never automatically retry an uncertain upload. |
| upload_reference_mediaA | Upload one user-authorized local MP4 video or WAV/MP3 audio for omni reference video generation. Requires a dedicated upload directory, user authorization for the specified files and local FFmpeg/FFprobe. Validates the real container and duration, re-encodes media and removes metadata, verifies login and returns an account-scoped reference_media_id. Existing storage URLs may be public. Does not generate or spend credits; never automatically retry an uncertain upload. |
| estimate_image_costA | Estimate image credits and save a 10-minute quote bound to the exact prompt, model options and uploaded reference IDs. Unless the user specified a model, pass default_model_type from list_image_models. Select the model’s image operation and reference limits from that catalog. Does not submit generation. |
| generate_imageA | Submit a quoted image request in the configured environment and consume that account credits. Requires a valid quote, stable request_id and maximum estimated credit budget. Identical retries return the saved task; uncertain submissions are never retried automatically. |
| get_image_taskA | Query a task created by TopMediAi-MCP using its request_id. After a successful status query, wait poll_after_seconds (normally 20 seconds) before querying this task again. Earlier or concurrent calls return cached:true with saved state and the remaining wait, without another backend request. Different tasks run independently without holding the store lock during network requests. Stop normal polling on completed or failed. Returns result URLs and image resource links. When images are available use preview_image_task and include clickable original links. Does not submit or charge for another generation. |
| preview_image_taskA | Show already generated images from a locally saved task in a read-only preview card with load/error/retry/original-link controls. Call after get_image_task returns images. Does not query the backend, download media, submit generation or spend credits. Host UI support is required; always also provide original result links. |
| get_generation_capabilitiesA | Inspect implementation readiness and approved route availability for Music, Video, TTS, STS, denoise, clone and MV. Does not call a backend. |
| get_music_entitlementsA | Query music entitlements. Display only universal credits from display.balances; music_credits are internal settlement data and must not be shown even when nonzero. The backend may initialize first-use entitlements. |
| get_video_entitlementsA | Query video entitlements through the membership backend. Display current universal credits only; legacy video_units are internal settlement data and must not be shown even when nonzero. May initialize first-use entitlements. |
| list_music_modelsA | List the complete current Web music catalog with capabilities and independent live pricing_status; prices never filter model visibility. When the user has not specified a model, use the returned default_mv. Current mv values: v6-pro, v6-wild-pro, v6-mini. |
| estimate_music_costA | Save a 10-minute music quote bound to exact input. Unless the user specified a model, pass default_mv from list_music_models. Returns alternative entitlement costs for internal budgets; show only universal credits from display.estimated_costs, never specialized credits or alternative-branch wording. Does not generate. |
| generate_musicA | Submit one quoted music generation. Requires paid and business switches, a stable request_id and budgets for every quoted resource. Budgets are local quote checks, not backend hard caps. Never automatically retry uncertain submission. |
| list_video_modelsA | List the complete current Web video catalog with capabilities and independent live pricing_status; prices never filter model visibility. When the user has not specified a model, use the returned default_model_type. Select text_to_video (default), image_to_video, image_to_video_start_end, reference_to_video or omni_reference_to_video. Variable duration models require the backend duration protocol ID and real_duration in seconds from capabilities. Select generate_audio to match the quote. |
| estimate_video_costA | Save a 10-minute video quote bound to exact input. Unless the user specified a model, pass default_model_type from list_video_models. Returns alternative entitlement costs for internal budgets; show only universal credits from display.estimated_costs, never specialized credits or alternative-branch wording. Does not generate. |
| generate_videoA | Submit one quoted video generation. Requires paid and business switches, a stable request_id and budgets for every quoted resource. Budgets are local quote checks, not backend hard caps. Never automatically retry uncertain submission. |
| get_speech_entitlementsA | Read speech characters, universal credits and full TTS generation permission from existing membership APIs. Voice-specific characters and multipliers are checked during a TTS estimate. |
| upload_speech_audioA | Upload one externally authorized audio file from TOPMEDIAI_UPLOAD_ROOT using existing upload and STS registration APIs. Maximum 50 MiB and 300 seconds; local FFmpeg/FFprobe required. Existing upload URLs may be public. Returns a local account-scoped speech_asset_id. No synthesis or automatic retry. |
| list_tts_modelsA | List TTS channels and parameters. Select a public voice_id using list_voices with operation=tts. Generation is synchronous and returns the audio directly. |
| estimate_tts_costB | Estimate TTS locally using backend text/SSML counting rules, account multipliers and current voice/account entitlements from existing APIs. Final settlement is performed by the synthesis backend. Show only display.estimated_costs as estimated credits, including when the selected entitlement uses characters. Raw costs retain the selected entitlement for budgets; do not show billable characters/seconds as the price. Does not synthesize. |
| generate_ttsA | Generate TTS synchronously: this call waits for audio and returns the completed result with model and available voice name. After success call preview_audio_task with the returned task_handle to show the inline player, and include a named original audio link. No extra get_generation_task polling is required. The card uses article_title and labels this as synthesized speech. Requires a quote, stable request_id and budget for the selected credits or characters. Timeout or cancellation may leave backend synthesis running; unknown submissions are never retried. |
| list_sts_modelsB | List STS channels and parameters. Select a public voice_id using list_voices with operation=sts. Generation is synchronous and returns the audio directly. |
| estimate_sts_costC | Save an STS quote using the authoritative speech backend preview. Show only display.estimated_costs as estimated credits, including when the selected entitlement uses characters. Raw costs retain the selected entitlement for budgets; do not show billable characters/seconds as the price. Does not synthesize. |
| generate_stsA | Generate STS synchronously: this call waits for audio and returns the completed result with model and available voice name. After success call preview_audio_task with the returned task_handle to show the inline player, and include a named original audio link. No extra get_generation_task polling is required. Label this as the converted result, not the source audio. Requires a quote, stable request_id and budget for the selected credits or characters. Timeout or cancellation may leave backend synthesis running; unknown submissions are never retried. |
| get_generation_taskA | Read an account-scoped task_handle created by this MCP. For music and video, wait poll_after_seconds (normally 20 seconds) after each successful status query before querying this task again. Earlier or concurrent calls return cached:true with saved state and the remaining wait, without another backend request. Stop normal polling on completed or failed. Synchronous speech reads saved local results without HTTP polling; successful speech calls already return audio. Music/video results resolve supported encoded addresses into artifacts[].url. When completed audio is available, call preview_audio_task once to show all successful versions in a player, and include named original audio links. Do not reopen the same card for unchanged polls. Deliver every successful artifact with model, voice where applicable, estimated consumption with its credit type, and known actual output duration. Do not mention missing actual consumption. When completed video is available, call preview_video_task once to show a video player, and include named original video links. Do not reopen unchanged cards. Browser navigation, screenshots and media downloads require an explicit user request. Never accepts arbitrary backend IDs. Uncertain submissions require website history reconciliation; no generation is retried. |
| preview_audio_taskA | Show generated music (vocal or instrumental) or speech from an owned locally saved task in an inline player. Call once when completed audio becomes available; shows separate versions, playback/seek controls, retry and original links. Playback starts only on user click. Reads saved results only: no backend polling, media download, generation, spending or configuration changes. Always also include named original audio links for hosts without UI support. |
| preview_video_taskA | Show generated videos from an owned locally saved task in an inline player. Call once when completed video becomes available; includes native playback, seek, volume, fullscreen, retry and original links. Playback starts only on user click. Reads saved results only: no backend polling, media download, generation, spending or configuration changes. Always also include named original video links for hosts without UI support. |
| list_voicesB | List public voices for operation tts (default) or sts. Uses bounded local pagination. Read get_voice_detail, then obtain an exact speech quote before generation. |
| get_voice_detailA | Read accent and emotion metadata for a public voice previously returned by list_voices in this session. Does not authorize or perform TTS. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| TopMediai image preview | Read-only image viewer for existing task results. |
| TopMediai audio preview | Read-only player for existing generated music and speech. |
| TopMediai video preview | Read-only player for existing generated videos. |
TDQS
Scored across 35 tools
Most tools are cleanly separated by resource and action (image/music/video/TTS/STS each have their own list/estimate/generate/get/preview family), and login, upload, and entitlement tools are distinct. There is minor overlap risk between get_image_task and get_generation_task, and among the several get_*_entitlements/get_balance tools, but the very detailed descriptions disambiguate them.
Nearly every tool follows a predictable verb_noun pattern with resource-qualified names (list_image_models, estimate_video_cost, generate_music, preview_audio_task, get_voice_detail). The convention is applied uniformly across login, upload, estimation, generation, and preview categories.
35 tools is heavy and above the comfortable range, though the breadth of features (five media types each with list/estimate/generate/get/preview, plus login and multiple upload flows) partly justifies it. Each tool nominally earns its place, but the surface is large enough to feel overwhelming.
Coverage is strong: login lifecycle, entitlements/balance, model catalogs, cost estimation, generation, task polling, previews, and uploads are all present for every supported medium. Minor gaps exist (no explicit logout/credential removal or generation-cancellation tool), which agents can work around.