ownta-mcp

OWNTA 的 MCP 服务端：把出图、出视频、图像处理、技能与百科只读封装成 Agent 可直接调用的 11 个工具。 两条接入方式——本地 stdio（pip install ownta-mcp）或远程 HTTP （https://ai.ownta.ai/mcp，不用装包）。

安装

pip install ownta-mcp
# 或者
uv tool install ownta-mcp

需要 Python >= 3.10。装完会得到命令 ownta-mcp（也可以 python -m mcp_server）。

1. 拿一把 Key

登录 https://ownta.ai → 设置 → API Key → 新建。

默认 scopes 是五个值：img.gen（出图）、vid.gen、llm.chat、img.ops（图像处理）、 lib.read。只让 Agent 出图就把 img.ops 去掉；Key 建完不能改 scopes，要改只能重建。 存量 Key 会在服务端启动迁移时自动补上 img.ops / lib.read，不需要重建。

Key 等同账户权限（能出图、能扣点），不要提交进仓库或贴进公开对话。

2. 配到客户端

通用形状（Claude Desktop / Cursor 都是 mcpServers 这一层）：

{
  "mcpServers": {
    "ownta": {
      "command": "ownta-mcp",
      "env": {
        "OWNTA_GW_API_KEY": "sk-ownta-...",
        "OWNTA_GW_BASE_URL": "https://ai.ownta.ai"
      }
    }
  }
}

• Claude Desktop：%APPDATA%\Claude\claude_desktop_config.json（Windows）/ ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• Cursor：~/.cursor/mcp.json
• VS Code：.vscode/mcp.json（键名是 servers，其余字段相同）

Windows 上客户端找不到 ownta-mcp 时，把 command 写成 pip 的 Scripts 全路径， 例如 C:\Users\<you>\AppData\Local\Programs\Python\Python312\Scripts\ownta-mcp.exe。

OWNTA_GW_BASE_URL 可省略，默认就是 https://ai.ownta.ai。

2b. 或者不装包：连远程 HTTP 端点

服务端在 https://ai.ownta.ai/mcp 跑了一份 streamable-http（无状态）。客户端支持 URL 时，不用装包、不用本机 Python：

{
  "mcpServers": {
    "ownta": {
      "url": "https://ai.ownta.ai/mcp",
      "headers": { "Authorization": "Bearer sk-ownta-..." }
    }
  }
}

• Key 放 Authorization 头；没带 Key 的请求在门口 401。
• 端点只做协议适配：scope、余额、日封顶仍由网关判定，错误码与 stdio 完全一致。
• 只支持 streamable-http（Claude Desktop 目前只起子进程，走第 2 步 stdio）；旧版 SSE transport（/sse）不提供。
• 远程与 stdio 是同一套 11 个工具、同一份计价，选哪种只取决于客户端能不能起子进程。

3. 先跑这一句

用 ownta 的 generate_image 画一只在雨林里的蓝顶亚马逊鹦鹉，1024x1024，然后轮询到出图，把图片 URL 给我。

Agent 应该先拿到 job_id，再调 query_job 取 url。第一次调用会扣点； 余额不足会收到 insufficient_credits。

想看视频：这一句按秒扣点

用 ownta 的 generate_video 生成一段 5 秒、16:9、720P 的视频：热带雨林里蓝顶亚马逊鹦鹉 缓慢推近，拿 job_id 轮询到成片，把 URL 给我。

generate_video 立即回 job_id，视频通常 15 分钟（H3 约 3 分钟）：隔 2030 秒 query_job 一次，不要在一次调用里等。默认 720P/5s/16:9 是最便宜的一档（H3 18 点/秒， 约 90 点）；1080P 28 点/秒；4K 110 点/秒且最长 8 秒；16~30 秒会切到长视频档（更贵）。 首帧参考图只收 https 直链或 base64，http:// 会被上游拒收。真实扣点以 query_job 的 credits_charged 为准，失败会退。余额可以先用 get_wallet 免费查。

想看「题材 × 风格」能拼成什么：这一句零扣点

先从 ownta 的百科里找「蓝顶亚马逊鹦鹉」，再找一条「3D 渲染」风格，用 compose_prompt 拼成提示词，把 prompt_zh 原样给我，先别出图。

预期三步：browse_library(domain="nature") 与 browse_library(domain="style", sub="form") 各取一条 path → compose_prompt(subject=…, style=…) → 回 prompt_zh / prompt_en / negative / blocks。blocks 固定三段（subject / form / constraints）， constraints 在最后 —— 工艺红线不能被风格覆盖。

拿到 prompt_zh 后再原样交给 generate_image(prompt=…)，这时才扣点。 negative 只作参考：generate_image 没有负向词入参，别拼进 prompt 正文（会稀释主体）。

不要自己拼：块序、工艺约束与负向词方向都由组合层决定，自己拼漏掉不报错， 只表现为「图不对但说不上为什么」，成本回到每次重生成的点数上。

工具

工具	scope	计费	说明
generate_image	img.gen	按计价表扣点	提交出图（异步，立即回 job_id）；支持参考图、透明底、DTF/DTG
generate_video	vid.gen	按秒扣点（720P 18 点/秒、1080P 28、4K 110）	提交出视频（异步，立即回 job_id）；默认 720P/5s/16:9，4K ≤8s，首帧可传 https/base64
generate_brazil_pattern	img.gen	按计价表扣点	巴西 T 恤印花一步提交（10 款技能，透明底 DTF）
query_job	—	免费	轮询任务状态与成品 URL，可反复调（图片与视频共用）
get_wallet	—	免费	查这把 Key 所属账户的余额（1 点 = 1 美分）
list_skills	—	免费	平台模板 + 你自己的「我的技能」
get_skill	—	免费	取单个技能的提示词全文与图位清单
apply_op	img.ops	按档 0~16 点（明细见下）	13 档图像处理；compress 兼做等比下采（没有 resize）
browse_library	—	免费	百科知识库目录与检索（10 个域，含 nature 题材 / style 风格层）
read_library_entry	—	免费	读百科正文或 references/ 附件，支持分段续读
compose_prompt	—	免费	把 1 条 nature 题材 + 1 条 style 造型（+ 可选配色）拼成成品提示词

apply_op 的 13 档按点数分四组（价目真值在网关 Price 表）：

• 0 点：compress / crop / watermark / print_text / whitebg
• 2 点：matting / kit　　4 点：seamless　　5 点：upscale　　6 点：seamless_pro
• 8 点：print_extract　　10 点：inpaint_swap　　16 点：outpaint

apply_op 的 src 只收本站 CDN 对象（image/ uploads/ processed/ 前缀）， 不收外链与 base64；generate_image 的参考图反过来只收 data URL / 裸 base64，不收 http URL。

错误码

回包 ok=false 时按 code 分支（原样透传网关的 detail.reason）：

code	含义	怎么办
insufficient_credits	余额不足	充值，或换一把有余额账号的 Key
scope_forbidden	这把 Key 没有该动作的 scope	apply_op 需要 img.ops，新建一把带它的 Key
rate_limited	触发 RPM / 突发 / 日封顶	按回包 retry_after 退避
content_blocked	内容审核拒了	改写提示词
invalid_request	参数或来源不合规	按 message 改；src 必须是本站对象

已知边界

• 远程端点只支持 streamable-http（无状态），不提供旧 SSE transport 与会话恢复； stdio 仍要求客户端能起子进程。
• 一次任务不等待出图/出片；generate_image / generate_video 返回后必须用 query_job 轮询。
• 视频比图片慢得多（H3 常见 15 分钟）：轮询间隔建议 2030 秒，别在一次工具调用里死等。
• stdout 是 JSON-RPC 通道，本包日志只写 stderr；不要用 print 调试。

从源码安装（开发）

cd gateway/mcp_server
pip install -e .

版本：0.2.0（PyPI）。相对 0.1.3 加两只工具：generate_video（vid.gen，按秒扣点， 默认 720P/5s/16:9，4K ≤8s）与 get_wallet（免费查余额），共 11 只。视频技能从这版起 runnable=true：duration_sec / aspect_ratio 留空时按技能标注提交；套图（batch）仍只能 在前端跑。之前 9 只工具的签名与回包未变；远程 /mcp 与本包同步。

0.1.3 只改文案：compose_prompt 的 hint 原本把 negative 说成「单独作负向词」，但 generate_image 没有负向词入参（网关 GenerateRequest 也没有这个字段），照做只会去调一个 不存在的参数。现在写成「仅作参考、别拼进正文」，并补了上面那句零扣点示例。

0.1.2 加 compose_prompt（当时共 9 只）：把 1 条 nature 题材 + 1 条 style 造型 （sub=form/print，可选 1 条 palette-light 配色）交给网关组合层，回 prompt_zh / prompt_en / negative / blocks。之前这一步只能让 Agent 自己拼——块序、工艺约束 （红线，必须压最后）与负向词方向都会漏，而漏掉那次不报错，只表现为「图不对但说不上为什么」。 0.1.1 的 8 只工具签名与回包未变。