XinYu AIXinYu AI
CLI

XinYu AI Command-Line Tool

Generate images, video, audio, and text from your terminal or CI — on your own account and balance. One binary, xinyu, with a built-in MCP server (xinyu mcp).

Overview

The xinyu CLI is a thin wrapper over the XinYu AI generation API, authenticated with a user-level API key. Pricing and limits are identical to the web app. Ideal for scripts, automation, and CI pipelines.

Pipe-friendly

--json goes to stdout, progress to stderr — pipe straight into jq.

Async, never lost

Generation is async; even if the wait times out you can retrieve it with job get.

Built-in MCP

xinyu mcp runs as an MCP server for agents.

Prerequisites: Node.js 18+ and a XinYu AI account.

Get an API Key

1

Log in to XinYu AI

Visit xinyuai.app and sign in to your account.
2

Open Settings → API Keys

Click your avatar at the bottom-left to open Settings, then find the "API Keys" panel.
3

Create & copy the key

Click "Create". The plaintext key (xys_live_...) is shown only once — copy it immediately.
An API key carries your account permissions and can spend your Xins. Never commit it or share it publicly. If leaked, revoke it immediately in Settings.

Install

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

# …or run any command without installing:
npx @xinyuai/cli <command>
Requires Node.js 18+. After installing, the xinyu command is available globally.

Log in

Login validates the key against the server and stores the credential in ~/.xinyu/credential.json (chmod 600).

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

You can skip login and use the env vars XINYU_API_KEY / XINYU_BASE_URL instead (they take precedence — handy in CI).

Commands

xinyu loginSave & validate your API key
xinyu logoutRemove the stored credential
xinyu whoamiShow the current login target
xinyu balanceShow your Xins balance
xinyu model listList models (filter by type)
xinyu project listList my projects (canvases) for a --project id
xinyu project createCreate a new empty canvas, returns its id
xinyu generate imageText-to-image / image-to-image
xinyu generate videoText-to-video / image-to-video
xinyu generate audioText-to-speech
xinyu generate textRun a text LLM
xinyu job get <id>Get a job's status & assets
xinyu job listList recent jobs
xinyu mcpRun the built-in MCP server

Common flags

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]

Examples

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"
By default it waits for the job and prints the asset URL(s) to stdout; add --no-wait to return the jobId immediately, then use xinyu job get.

Async & Timeouts (no result is ever lost)

Generation runs asynchronously on the platform, fully decoupled from whether the CLI is still waiting. --wait only controls local polling; --timeout defaults to 300s for images/audio and 1200s (20 min) for video, and can go up to 3600s — matching the platform's own ceiling.

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...

A wait timeout is not an error: the CLI prints the jobId and exits while the job keeps running server-side. When it finishes, the asset is saved to your account (and into the canvas project if you passed --project) — retrieve it any time with xinyu job get. Billing is charged at creation and auto-refunded on failure or ~60-min timeout, so you're never double-charged and never lose a successful result.

Use as an MCP server

xinyu mcp starts a stdio MCP server using your stored credential, exposing all 14 generation tools to any MCP client.

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

For the full MCP connection guide, see the MCP guide.

FAQ