@xinyuai/cli

The XinYuAi command-line interface. Generate images, video, audio, and text from your terminal or CI — and run a built-in MCP server with xinyu mcp.

It is a thin wrapper over the XinYuAi generation API, authenticated with a user-level API key. Same pricing, balance, and limits as the web app.

Install

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

Or run it without installing:

npx @xinyuai/cli <command>       # e.g. npx @xinyuai/cli balance

cd packages/cli
pnpm install --ignore-workspace
pnpm build      # → dist/cli.js  (bin name: xinyu)

Run it via node dist/cli.js <command>, or npm link to expose xinyu globally.

Authentication

# Interactive (prompts for the key), or pass --key directly:
xinyu login --key xys_live_xxxx --base-url https://xinyuai.app

The credential is validated against the server and stored in ~/.xinyu/credential.json (chmod 600). You can also skip login and use environment variables XINYU_API_KEY / XINYU_BASE_URL (these take precedence).

Create an API key in the web app under Settings → API Keys.

Commands

xinyu login [--key <key>] [--base-url <url>]   # save & validate credential
xinyu logout                                   # remove stored credential
xinyu whoami                                   # show current login target

xinyu balance [--json]                         # Xins balance
xinyu model list [--type IMAGE|VIDEO|AUDIO] [--json]

xinyu generate image  --prompt <p> --project <id> [--model <m>] [--aspect <r>]
                      [--size 1K|2K|4K] [--ref <url...>] [--count <n>]
                      [--no-place-on-canvas] [--no-wait] [--timeout <s>] [--json]
xinyu generate video  --prompt <p> --project <id> [--model <m>] [--aspect <r>]
                      [--duration <s>] [--resolution <r>] [--audio]
                      [--start-image <url>] [--end-image <url>]
                      [--no-place-on-canvas] [--no-wait] [--json]
xinyu generate audio  --text <t> --project <id> [--voice <v>] [--no-wait] [--json]
xinyu generate text   --prompt <p> [--model <m>] [--json]

# Every generation must belong to a canvas — pass --project <id>.
# Get one with `xinyu project list` or create one with `xinyu project create`.
# Image/video land on the canvas as nodes by default (--no-place-on-canvas to opt out).

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

xinyu mcp [--base-url <url>]                    # run the built-in MCP server (stdio)

By default generation commands wait for the job to finish and print the asset URL(s) to stdout. Use --no-wait to get the job id immediately, then xinyu job get <id>. Progress messages go to stderr, so --json output on stdout stays clean and pipe-friendly.

Async jobs & timeouts (no result is ever lost)

Generation runs asynchronously on the platform, fully decoupled from whether the CLI is still waiting. --wait only controls how long the CLI polls locally before it stops.

Default --timeout: 300s for images/audio, 1200s (20 min) for video. Video (esp. Seedance 2.0) usually takes 10-20 min and occasionally up to ~60; you can raise --timeout up to 3600s, which matches the platform's own processing ceiling.

If the wait elapses, the CLI does not error — it prints the jobId and exits, while the job keeps running server-side:

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

When the platform finishes, the asset is saved to your account (and into the canvas project if you passed --project). Retrieve it any time:

xinyu job get 7f3a...        # prints status + asset URL(s) once ready

Billing is charged at creation and auto-refunded if the job ultimately fails or times out (~60 min) — so you're never double-charged and never lose a successful result.

Examples

# First, get a canvas to generate into (or create one)
PROJECT=$(xinyu project create --name "CI renders" --json | jq -r '.id')

# Generate an image into that canvas and grab the URL in CI
URL=$(xinyu generate image --prompt "a beach at sunset" --model nano-banana-2 \
        --size 2K --project "$PROJECT" --json | jq -r '.assets[0]')

# Make a 5s video, don't block
xinyu generate video --prompt "ocean waves" --model seedance-2 --duration 5 \
        --project "$PROJECT" --no-wait

# Ask an LLM (text doesn't need a canvas)
xinyu generate text --prompt "summarize MCP in one sentence"

Built-in MCP server

xinyu mcp starts the same MCP server as @xinyuai/mcp-server, using your stored credential. Point any MCP client at it:

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

See the /mcp page in the web app for the full connection guide.

Development

pnpm dev -- balance     # run from source with tsx
pnpm typecheck