XinYu.
導覽
開發者
MCPCLI
語言
CLI

XinYu AI 命令列工具

在終端或 CI 裡生成影像、影片、音訊和文本,也能整理畫布,用的是你自己的帳戶和額度。一個執行檔 xinyu,還內建了 MCP server(xinyu mcp)。

概述

xinyu CLI 是 XinYu AI 生成介面的輕量封裝,用使用者級 API Key 驗證,計費與網頁端完全一致。適合指令碼、自動化和 CI 流水線。

管道友善

--json 輸出走 stdout,進度走 stderr,可直接 | jq。

非同步不丟

生成在平臺非同步跑,等待超時也能用 job wait / job get 取回。

內建 MCP

xinyu mcp 直接作為 MCP server 給 Agent 使用。

前置要求:Node.js 18 或更高版本,以及一個 XinYu AI 帳戶。

獲取 API Key

1

登入 XinYu AI

訪問 xinyuai.app 並登入你的帳戶。
2

開啟「個人設定」→「開發者 API 金鑰」

點選右上角頭像,選擇「個人設定」,在頁面下方找到「開發者 API 金鑰」。
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 price生成前估價(僅影像),與伺服器計費用同一個函式
xinyu presets瀏覽心宇預設(1407 套服裝、288 個人偶姿勢),按分類 / 機位 / 編號篩選
xinyu preset-import把一張預設存成自己的素材,拿到能當參考圖的 URL(預設原地址不能直接當參考,不扣心點)

專案與素材

xinyu project list列出我的專案(畫布),拿到 --project 用的 id
xinyu project create新建一個空畫布並返回 id
xinyu project assets搜尋 / 列出畫布裡已有的素材,拿到可複用的 URL(-q 按標題與完整提示詞搜尋)
xinyu project read畫布概覽:節點 / 連線總數與各型別的計數
xinyu project arrange整理畫布:把散落的內容節點按網格排好
xinyu project delete刪除空畫布(沒有節點、沒有生成結果);有內容的畫布請在網頁裡刪
xinyu upload上傳本地圖片 / 影片 / 音訊,列印可用於生成的 URL(--place 同時放到畫布)

生成與編輯

xinyu generate image文生圖 / 圖生圖
xinyu generate video文生影片 / 圖生影片 / 參考生影片
xinyu generate final把 Seedance 2.5 樣片渲染成 1080p 或 4K 正片
xinyu generate audio文字轉語音 / Seed Audio
xinyu generate text文本 LLM 對話
xinyu generate enhance影像高畫質放大與增強(Topaz)
xinyu generate rembg摳圖 / 去背景(透明 PNG)
xinyu generate layers拆圖層:底圖 + 透明 PNG 圖層(按上限先扣,多扣的自動退回)
xinyu generate outpaint影像外繪:向任意一邊按畫素外擴
xinyu generate image-edit指令式影像編輯(重繪或擦除)
xinyu generate video-edit指令式影片編輯(Kling O3,源影片高度至少 720px)
xinyu generate video-action放大或延長此前生成的 Grok 影片

畫布節點

xinyu node create新建待生成節點(設好提示詞、模型、引數、參考,不生成、不扣心點)
xinyu node find按標題 / 提示詞、型別、狀態、分組或位置搜節點(只讀)
xinyu node inspect檢視最多 8 個節點的完整資訊:提示詞、引數、連結、連線和 revision(只讀)
xinyu node read-prompt分段讀取節點的完整提示詞(只讀)
xinyu node rename修改畫布節點的標題
xinyu node connect給兩個節點連上參考線
xinyu node disconnect移除節點間的參考線
xinyu node delete刪除節點及其連線(不可恢復;已出結果或生成中的節點需加 --confirm-*)
xinyu node set-params就地修改節點的生成引數(只存草稿,不重新生成、不花心點)

任務與 MCP

xinyu job get查詢單個任務狀態與產物
xinyu job wait一直等到任務結束(等待超時後找回結果的首選)
xinyu job list列出最近任務(可按狀態 / 畫布過濾)
xinyu mcp內建 stdio MCP server

常用引數

bash
xinyu login [--key <key>] [--base-url <url>]
xinyu logout
xinyu whoami
xinyu balance [--json]
xinyu model list [--type IMAGE|VIDEO|AUDIO] [--json]
xinyu price --model <m> [--size <s>] [--count <n>] [--refs <n>] [--json]
xinyu presets [--group clothing|pose] [--category <c>] [--angle <a>] [-q <text>]
              [--offset <n>] [--limit <n>] [--json]
xinyu preset-import <presetUrl> [--project <id>] [--place] [--json]

xinyu project list    [--search <text>] [--limit <n>] [--json]
xinyu project create  --name <name> [--description <text>] [--json]
xinyu project assets  <projectId> [-q <text>] [--type IMAGE|VIDEO|AUDIO]
                      [--page <n>] [--limit <n>] [--json]
xinyu project read    <projectId> [--limit <n>] [--json]
xinyu project arrange <projectId> [--columns <n>] [--gap <n>] [--json]
xinyu project delete <projectId> [--json]   # empty canvases only
xinyu upload <file> [--project <id>] [--place] [--json]

xinyu generate image --prompt <p> --project <id> [--model <m>] [--aspect <r>]
                     [--size <s>] [--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>]
                     [--element-image <url...>] [--ref-video <url...>] [--ref-audio <url...>]
                     [--draft] [--x <n>] [--y <n>] [--no-place-on-canvas]
                     [--no-wait] [--timeout <s>] [--json]
xinyu generate final <draftJobId> --project <id> [--resolution <r>]
                     [--no-wait] [--timeout <s>] [--json]
xinyu generate audio --text <t> --project <id> [--model <m>] [--voice <v>] [--no-wait] [--json]
xinyu generate text  --prompt <p> [--model <m>] [--media <url...>] [--project <id>] [--json]

xinyu generate enhance      --image <url> --project <id> [--upscale-factor <n>]
                            [--no-face-enhancement]
xinyu generate rembg        --image <url> --project <id> [--mask]
xinyu generate layers       --image <url> --project <id> [--max <n>] [--size 1K|2K] [--text]
xinyu generate outpaint     --image <url> --project <id> [--top <n>] [--right <n>]
                            [--bottom <n>] [--left <n>]
xinyu generate image-edit   --prompt <t> --image <url> --project <id> [--model <m>] [--mode <m>]
xinyu generate video-edit   --prompt <t> --video <url> --project <id>
                            [--duration <s>] [--keep-audio]
xinyu generate video-action --action <a> --source-task-id <id> --project <id>
                            [--extend-times <n>]
# Results land on the canvas by default. All commands above except text accept:
#   [--title <text>] [--x <n>] [--y <n>] [--no-place-on-canvas]

xinyu node create <image|video|audio|text> --project <id> [--prompt <t>] [--model <m>]
                  [--title <t>] [--set <key=value...>] [--ref <nodeId...>]
xinyu node find --project <id> [-q <text>] [--type <t...>] [--status <s>]
xinyu node inspect <nodeId...> --project <id>
xinyu node read-prompt <nodeId> --project <id> [--offset <n>]
xinyu node rename <nodeId> --project <id> --title <title>
xinyu node connect <sourceId> <targetId> --project <id>
xinyu node disconnect <sourceId> <targetId> --project <id>
xinyu node delete <nodeId...> --project <id> [--confirm-finished] [--confirm-running]
xinyu node set-params <nodeId> --project <id> --set <key=value...> [--confirm-finished] [--confirm-running]

xinyu job get  <jobId> [--json]
xinyu job wait <jobId> [--timeout <s>] [--json]
xinyu job list [--status <s>] [--project <id>] [--limit <n>] [--json]

xinyu mcp

# --project is required for every generate command except `generate text`:
# every result belongs to a canvas. Get an id with `xinyu project list`
# or `xinyu project create`. Run `xinyu <command> --help` for every flag.
# Valid values for --size / --duration / --resolution depend on the model:
# see `xinyu model list --json`.

示例

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

# Ask what an image would cost before spending anything
xinyu price --model nano-banana-2.1 --size 2K --count 2

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

# Upload a local image, then animate it as the first frame
IMG=$(xinyu upload ./character.png)
xinyu generate video --prompt "she turns and smiles" --model seedance-2 \
        --start-image "$IMG" --duration 5 --project "$PID"

# Lost the id after a timeout? Find the job, then wait for it
xinyu job list --status RUNNING --project "$PID"
xinyu job wait <jobId>

# Ask an LLM
xinyu generate text --prompt "summarize MCP in one sentence"
生成類命令預設會等待任務完成並把產物 URL 打到 stdout;加 --no-wait 立即返回 jobId,之後用 xinyu job wait 或 xinyu job get 取回。generate 可縮寫為 gen,project 可寫作 canvas。node 系列(改標題 / 連線 / 刪除 / 改引數)目前只支援個人畫布,團隊畫布會被拒絕。

非同步與超時(結果絕不丟失)

生成在平臺非同步執行,和 CLI 是否在等待完全解耦。--timeout 只控制 CLI 在本地等多久:影像、音訊類命令預設 300 秒,影片類命令(generate video / final / video-edit / video-action)預設 2400 秒(40 分鐘),job wait 預設 600 秒。平臺會把約 60 分鐘仍沒有產出的任務判定失敗並退款,所以 --timeout 設到 3600 秒(60 分鐘)就足夠了。

bash
$ xinyu generate video --prompt "..." --model seedance-2 --project "$PID" --timeout 1200
Job 7f3a… queued (40 Xins) — waiting...
Stopped waiting after 1200s — the job is STILL RUNNING and you have already paid 40 Xins for it.
Do not run the generate command again; resume it instead:
  xinyu job wait 7f3a…          # blocks until it finishes
  xinyu job list --status RUNNING  # if you lost the id

等待超時不會報錯:CLI 會列印 jobId 和繼續等待的辦法後退出,任務仍在伺服器繼續跑。用 xinyu job wait 繼續等,或用 xinyu job get 查一次;忘了 id 就用 xinyu job list --status RUNNING。完成後產物儲存到你的帳戶(指定 --project 則進入對應畫布專案)。計費在建立時扣除;任務失敗會自動退款,長時間(約 60 分鐘以上)沒有產出的任務,平臺也會自動判定失敗並退款——既不會重複扣費,也不會丟成功結果。請不要因為超時而重新執行 generate 命令。

作為 MCP server 使用

xinyu mcp 會用你儲存的憑證,作為 stdio MCP server 啟動,把 MCP 頁列出的全部工具(生成、編輯、任務、畫布讀寫)暴露給任意 MCP 客戶端。

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

完整的 MCP 連線說明見 MCP 指引頁。

常見問題