MCP · API

MCP 接入

让 Cursor、Claude Code、Claude Desktop 等 AI Agent 直接调用 tvvv 生成图片和视频。tvvv 提供一个标准的远程 MCP 服务器：Agent 用你的 API 密钥连上后，就能查模型、查余额、出图、出视频，费用从你的积分里扣，结果自动保存到你的作品库。

STEP 1

创建密钥

在下方生成一个 API 密钥（只显示一次）

STEP 2

粘贴配置

把配置片段贴进你的 Agent 客户端

STEP 3

告诉 Agent 怎么用

把使用说明（skill）贴给 Agent

API 密钥

…

配置片段

~/.cursor/mcp.json（或项目里的 .cursor/mcp.json）

{
  "mcpServers": {
    "tvvv": {
      "url": "https://tvvv.net/api/mcp",
      "headers": {
        "Authorization": "Bearer tvvv_sk_你的密钥"
      }
    }
  }
}

保存后在 Cursor 设置 → MCP 里确认 tvvv 显示为已连接（绿点）。

可用工具

list_models列出可用的图片 / 视频模型、参数和价格

get_balance查询积分余额和可用额度

generate_image生成 1–4 张图片（同步，返回签名链接）

generate_video提交视频任务（异步，立即返回 job_id）

get_job_status查询视频进度，完成后返回签名链接

每次生成前按预估校验余额（会扣除进行中视频任务占用的额度），不够直接拒绝、不扣费；实际按用量扣积分，通常不高于预估。返回的链接约 6 小时有效，作品永久保存在作品库。

Agent 使用说明（skill）

把下面这段贴给你的 Agent（例如 Cursor 的 Rules、Claude 的项目说明 / CLAUDE.md、或对话开头），它就知道什么时候用哪个工具、怎么写提示词、视频要轮询。

tvvv-skill.md

# tvvv.net 生成工具（MCP）使用说明

你可以通过 tvvv MCP 工具为用户生成图片和视频，费用从用户的 tvvv.net 积分里扣（10 积分 = 1 元人民币，按模型实际用量计费；list_models 会给出每个模型的积分价格），结果自动保存到用户的 tvvv.net 作品库。

## 什么时候用哪个工具
- list_models：第一次使用、或用户没指定模型时先调用，查看模型 id、支持的比例/分辨率/时长和价格。
- get_balance：生成前（尤其是视频）确认可用积分；余额不足时告诉用户去 https://tvvv.net/account?tab=billing 充值，不要反复重试。
- generate_image：出图（同步，约 10–60 秒）。便宜试稿用 meta/muse-image；要高质量或改图（带参考图）用 Seedream / GPT Image / Nano Banana。
- generate_video：出视频（异步）。立即返回 job_id，不会马上出片。
- get_job_status：拿 job_id 轮询视频进度。

## 视频要几分钟
- 视频通常 1–10 分钟。提交后每 20–30 秒调用一次 get_job_status，直到 status 为 completed（拿 video_url）或 failed（把 error 原样告诉用户）。
- 不要重复提交同一个视频来"加速"，每次提交都会占用积分。
- 先用短时长、低分辨率（如 5 秒 720p）确认效果，再出长片/高清。

## 提示词技巧
- 图片：主体 + 外观细节 + 场景 + 构图/镜头 + 光线 + 风格；需要画面里出现文字时，用引号写出确切文字。
- 视频：一句话写清主体和动作，再写镜头运动（推近、环绕、跟拍）、节奏、风格和声音；一个镜头只写一件主要的事。
- 图生视频：first_frame_url 传首帧图片（公网 https 链接），提示词只描述"接下来发生什么"。
- 参考图、首尾帧都必须是公网 https:// 链接（可以用 generate_image 返回的链接）。

## 费用与安全
- 每次生成前会按预估校验余额，不够会直接拒绝并返回所需积分。
- 实际扣费按用量结算，通常不高于预估。
- 返回的图片/视频链接约 6 小时后过期，需要长期保存请让用户在 tvvv.net 作品库下载。