XinYu.
CLI

XinYu AI 命令行工具

在终端或 CI 里生成图像、视频、音频和文本，用的是你自己的账户和额度。一个二进制 xinyu，还内置了 MCP server（xinyu mcp）。

概述

xinyu CLI 是 XinYu AI 生成接口的轻量封装，用用户级 API Key 鉴权，计费与限额和网页端完全一致。适合脚本、自动化和 CI 流水线。

管道友好

--json 输出走 stdout，进度走 stderr，可直接 | jq。

异步不丢

生成在平台异步跑，等待超时也能 job get 取回。

内置 MCP

xinyu mcp 直接作为 MCP server 给 Agent 使用。

前置要求：Node.js 18 或更高版本，以及一个 XinYu AI 账户。

获取 API Key

1

登录 XinYu AI

访问 xinyuai.app 并登录你的账户。
2

打开设置 → API Keys

点击左下角头像进入设置，找到「API Keys」面板。
3

创建并复制密钥

点击「创建」，明文密钥（xys_live_...）只显示一次，请立即复制保存。
API Key 等同于你的账户权限，可消耗心点。不要提交到代码仓库或公开分享；若泄露，立即在设置中吊销。

安装

bash
# Install the `xinyu` command globally
npm install -g @xinyuai/cli

# …or run any command without installing:
npx @xinyuai/cli <command>
需要 Node.js 18 及以上版本。装完后 xinyu 命令即可全局使用。

登录

登录会向服务器校验密钥，并把凭证保存到 ~/.xinyu/credential.json（权限 600）。

bash
# Pass --key directly, or omit it to be prompted
xinyu login --key xys_live_xxxxxxxxxxxx --base-url https://xinyuai.app

也可以不登录，直接用环境变量 XINYU_API_KEY / XINYU_BASE_URL（优先级更高，适合 CI）。

命令

xinyu login保存并校验 API Key
xinyu logout移除本地凭证
xinyu whoami查看当前登录目标
xinyu balance查询心点余额
xinyu model list列出可用模型（可按类型过滤）
xinyu project list列出我的项目（画布），拿到 --project 用的 id
xinyu project create新建一个空画布并返回 id
xinyu generate image文生图 / 图生图
xinyu generate video文生视频 / 图生视频
xinyu generate audio文字转语音
xinyu generate text文本 LLM 对话
xinyu job get <id>查询单个任务状态与产物
xinyu job list列出最近任务
xinyu mcp内置 stdio MCP server

常用参数

bash
xinyu project list   [--search <text>] [--limit <n>] [--json]
xinyu project create --name <name> [--description <text>] [--json]

xinyu generate image --prompt <p> --project <id> [--model <m>] [--aspect <r>]
                     [--size 1K|2K|4K] [--ref <url...>] [--count <n>] [--x <n>] [--y <n>]
                     [--no-place-on-canvas] [--no-wait] [--timeout <s>] [--json]

xinyu generate video --prompt <p> --project <id> [--model <m>] [--duration <s>]
                     [--resolution <r>] [--audio] [--start-image <url>] [--end-image <url>]
                     [--x <n>] [--y <n>] [--no-place-on-canvas] [--no-wait] [--json]

xinyu generate audio --text <t> --project <id> [--voice <v>] [--json]
xinyu generate text  --prompt <p> [--model <m>] [--json]

# --project is required for image/video/audio: every result belongs to a canvas.
# Get an id with `xinyu project list` or `xinyu project create`.

xinyu job get <jobId> [--json]
xinyu job list [--status <s>] [--limit <n>] [--json]

示例

bash
# Create (or pick) a canvas first — every generation needs one
PID=$(xinyu project create --name "My Canvas" --json | jq -r '.id')

# Grab a generated image URL in CI (clean JSON on stdout)
URL=$(xinyu generate image --prompt "a beach at sunset" \
        --model nano-banana-2 --size 2K --project "$PID" --json | jq -r '.assets[0]')

# Drop a video onto the canvas as a node (default — use --no-place-on-canvas to skip)
xinyu generate video --prompt "ocean waves" --model seedance-2 \
        --duration 5 --project "$PID"

# Ask an LLM
xinyu generate text --prompt "summarize MCP in one sentence"
默认会等待任务完成并把产物 URL 打到 stdout；加 --no-wait 立即返回 jobId，之后用 xinyu job get 查询。

异步与超时（结果绝不丢失）

生成在平台异步运行，和 CLI 是否在等待完全解耦。--wait 只控制 CLI 本地轮询多久；--timeout 默认图像/音频 300 秒、视频 1200 秒（20 分钟），最长可设 3600 秒，对齐平台自身的处理上限。

bash
$ xinyu generate video --prompt "..." --model seedance-2 --timeout 1200
Job 7f3a... queued (40 Xins) — waiting...
Stopped waiting after 1200s, but job 7f3a... is still running on the server
(no result lost). Check later with: xinyu job get 7f3a...

等待超时不会报错：CLI 打印 jobId 后退出，任务仍在服务器继续跑。完成后产物保存到你的账户（指定 --project 则进入对应画布项目），随时用 xinyu job get 取回。计费在创建时扣除，失败或约 60 分钟超时会自动退款——既不会重复扣费，也不会丢成功结果。

作为 MCP server 使用

xinyu mcp 会用你保存的凭证，作为 stdio MCP server 启动，把 14 个生成工具暴露给任意 MCP 客户端。

json
{
  "mcpServers": {
    "xinyu": {
      "command": "xinyu",
      "args": ["mcp"]
    }
  }
}

完整的 MCP 连接说明见 MCP 指引页。

常见问题