lingjing-cli

CLI & MCP Server for JDCloud Lingjing image and video generation APIs.

📦 Installation

# Install globally
npm install -g lingjing-cli

# Or use directly via npx
npx lingjing-cli

If you are running from the source code locally, you can use npm run build and then run node dist/cli.js instead of lingjing.

⚙️ Configuration

Set your API key via environment variables:

export LINGJING_API_KEY="your_api_key_here"
# Alternatively, you can use JDCLOUD_API_KEY

You can also use a .env file in the current directory, or specify one via --env-file <path>.

Global CLI Options

lingjing [global-options] <command> [options]

• --env-file <path>: Load env vars from a specific file
• --skip-env: Disable auto-loading .env
• --api-key <key>, -k: Override API Key
• --base-url <url>: Override API base URL (default: https://model.jdcloud.com)
• --request-id <id>: Specify a custom x-jdcloud-request-id header
• --json: Output pure JSON (useful for pipelines and parsing)

🚀 CLI Commands

1. Model Presets (preset)

See the available, ready-to-use model presets:

# List all presets
lingjing preset list

# Filter by type (image | video)
lingjing preset list --type image

# Filter by provider (e.g., kling, doubao, vidu, hailuo)
lingjing preset list --provider kling --type video

# Find presets by supported parameter / input type
lingjing preset list --supports-param multi_shot --supports-input image_url

# Compact browsing output
lingjing preset list --compact

# Get a single preset with full capSpec
lingjing preset get kling-v3-ttv

1.1 Capability Reference (Machine-readable First)

Each preset now has a capSpec with stable structure:

• summary: short capability summary
• inputs: supported input types (text_prompt, image_url, image_list, ref_video)
• params: parameter specs (type, required, default, enum, range, description)
• constraints: model-specific limitations and conditional support
• examples: minimal example payload fragments

2. Image Generation (image)

Submit an image generation task and wait for the result automatically:

# Doubao SeedDream 4.0
lingjing image \
  --preset doubao-seedream-4-0 \
  --params '{"prompt":"一只戴墨镜的猫","size":"2048x2048","taskNum":1}'

# Kling Image Generation
lingjing image \
  --preset kling-v2-1-image \
  --params '{"prompt":"城市夜景，赛博朋克风格","aspect_ratio":"16:9"}'

# Submit only (without waiting/polling), returns genTaskId
lingjing image \
  --preset doubao-seedream-4-0 \
  --params '{"prompt":"山间晨雾"}' \
  --no-wait

3. Video Generation (video)

Submit a video generation task and wait for the result:

# Text-to-Video: Kling V3
lingjing video \
  --preset kling-v3-ttv \
  --params '{"prompt":"海边日落，海浪轻拍礁石","duration":"5","mode":"pro","aspect_ratio":"16:9"}'

# Text-to-Video: Doubao Seedance 1.5 Pro
lingjing video \
  --preset doubao-seedance-1-5-pro-ttv \
  --params '{"prompt":"雪山脚下奔跑的骏马","aspect_ratio":"16:9"}'

# Image-to-Video: Kling V3 (Requires a reference image)
lingjing video \
  --preset kling-v3-ptv \
  --params '{"prompt":"人物转身微笑","image_url":"https://example.com/ref.jpg","duration":"5"}'

# Custom polling interval and timeout
lingjing video \
  --preset vidu-q2-ttv \
  --params '{"prompt":"极光下的雪原"}' \
  --interval 10 --timeout 300

Overriding specific parameters inline (--set): You can use --set key=value to override params fields easily:

lingjing video \
  --preset kling-v3-ttv \
  --params '{"prompt":"星空延时摄影"}' \
  --set duration=10 \
  --set aspect_ratio=9:16

4. Task Management (task)

If you submitted a task using --no-wait, you can query or poll its status later using its genTaskId:

# Query the current status of a task
lingjing task get <genTaskId>

# Polling a task until it completes or times out
lingjing task wait <genTaskId> --interval 5 --timeout 600

Task Status Reference:

• taskStatus=4: Success
• taskStatus=2: Failure

🤖 MCP Server

lingjing-cli can operate as an MCP (Model Context Protocol) server via stdio.

Start MCP Server

# Run globally installed version:
LINGJING_API_KEY=your_key lingjing-mcp

# Or via the CLI subcommand:
LINGJING_API_KEY=your_key lingjing mcp

# Load from an explicitly defined .env file:
LINGJING_ENV_FILE=/path/to/.env lingjing-mcp

Claude Desktop Integration

You can easily add the MCP server to Claude Code or Claude Desktop.

For Claude Code:

claude mcp add lingjing-cli -- npx -y lingjing-cli mcp

(Make sure to configure your LINGJING_API_KEY in your environment or via the LINGJING_ENV_FILE variable)

For Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "lingjing": {
      "command": "npx",
      "args": ["-y", "lingjing-cli", "mcp"],
      "env": {
        "LINGJING_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available MCP Tools

| Tool | Description | |---|---| | list_presets | List presets with full capability specs; supports capability/provider/input/param filters and compact mode. | | get_preset_capability | Get full capability spec for one preset. | | find_presets_by_capability | Find presets by supported input/parameter capability (compact optional). | | generate_image | Submit an image generation task and wait for the result automatically. | | generate_video | Submit a video generation task and wait for the result automatically (default timeout 600s). |

list_presets

| Parameter | Type | Description | |---|---|---| | capability | image | text-to-video | image-to-video | reference-to-video | Filter by capability (optional) | | provider | doubao | hailuo | kling | paiwo | vidu | Filter by provider (optional) | | supportsParam | string | Filter by supported parameter name (optional) | | supportsInput | text_prompt | image_url | image_list | ref_video | Filter by supported input type (optional) | | compact | boolean | Compact output mode (default: false) |

get_preset_capability

| Parameter | Type | Description | |---|---|---| | preset | string | Preset key, e.g., kling-v3-ttv |

find_presets_by_capability

| Parameter | Type | Description | |---|---|---| | capability | image | text-to-video | image-to-video | reference-to-video | Filter by capability (optional) | | provider | doubao | hailuo | kling | paiwo | vidu | Filter by provider (optional) | | supportsParam | string | Filter by supported parameter name (optional) | | supportsInput | text_prompt | image_url | image_list | ref_video | Filter by supported input type (optional) | | compact | boolean | Compact output mode (default: false) |

generate_image / generate_video

| Parameter | Type | Default | Description | |---|---|---|---| | preset | string | — | The preset key, e.g., doubao-seedream-4-0 | | params | object | — | Task parameter object (e.g., prompt, aspect_ratio) | | interval | number | 5 | Polling interval in seconds | | timeout | number | 300 / 600 | Max waiting time in seconds |

Returns: { submit, result, urls }, where urls easily provides the extracted direct links to the generated media.

License

MIT