Unofficial PicLumen Toolkit

English | 简体中文 | 日本語 | Français

An unofficial PicLumen Node.js toolkit for local automation, scripting, and research-oriented integrations. It wraps image generation, video generation, file upload, task querying, and a reusable grouped API surface.

Positioning

• Unofficial project. Not affiliated with PicLumen.
• Intended for local automation and integration under accounts you are authorized to use.
• Provides a reusable client, CLI commands, and grouped client.api.* accessors.

Features

• Create image generation tasks
• Create video generation tasks
• Request temporary upload credentials and upload files to COS
• Query queue, history, and cancel tasks
• Access grouped API modules through client.api.*
• Run a local pipeline from reference image to image to video

Responsible Use

• This repository is for interoperability research, personal automation, and local integration.
• Make sure your usage complies with PicLumen terms, account permissions, rate limits, and copyright requirements.
• The repository does not include real tokens, real account data, or production secrets.

Requirements

• Node.js 18+
• A PicLumen session token from an account you are authorized to use

Install

npm install

Authentication

Prefer environment variables:

# macOS / Linux
export PICLUMEN_AUTH_TOKEN="your-piclumen-token"

# Windows PowerShell
$env:PICLUMEN_AUTH_TOKEN="your-piclumen-token"

You can also use a local config file:

copy piclumen-auth.example.json piclumen-auth.json

piclumen-auth.json is ignored by Git and should never be committed.

If you want to use Chrome-based local session loading, read SECURITY.md first and keep that usage limited to your own machine.

Quick Start

Check authentication:

npm run auth
npm run me

List models:

npm run models

Show CLI help:

npm run cli -- help

Common CLI Commands

Create an image:

npm run cli -- create-image \
  --model "your-model-id" \
  --prompt "orange cat icon on white background"

Create a video:

npm run cli -- create-video \
  --model "your-model-id" \
  --prompt "a cute dog walks in a cozy kitchen" \
  --duration 5 \
  --ratio 720P

Query tasks:

npm run queue
npm run history -- --page-size 5

Upload a file:

npm run cli -- upload --file "C:/absolute/path/demo.png"

API Usage

Use the grouped API collection when you want this repository to act like a reusable local API layer:

const { createApi } = require('./shared/client-factory');

async function main() {
  const api = createApi();

  const me = await api.user.getInfo();
  const models = await api.models.listInternal();

  const result = await api.generation.image({
    modelId: models[0].model,
    prompt: 'orange cat icon on white background',
    width: 1024,
    height: 1024,
  });

  console.log({
    userId: me.userId,
    taskMarkId: result.markId,
  });
}

main().catch(console.error);

If you already manage a PiclumenClient instance directly:

const { PiclumenClient } = require('./src/core/piclumen-client');

async function main() {
  const client = new PiclumenClient({
    authToken: process.env.PICLUMEN_AUTH_TOKEN,
  });

  const queue = await client.api.tasks.getQueue();
  const history = await client.api.tasks.getHistory({ pageNum: 1, pageSize: 10 });

  console.log({
    queueSize: queue?.concurrentJobList?.length || 0,
    historyCount: history?.list?.length || 0,
  });
}

main().catch(console.error);

Available API groups:

• api.user
• api.models
• api.tasks
• api.uploads
• api.generation
• api.community
• api.auth
• api.request(...)

Pipeline Script

src/core/pipeline.js runs a local automation chain:

1. Pick a reference image from IPS/
2. Upload the reference image
3. Generate an image with Banana2
4. Generate a video from the resulting image

Example:

npm run pipeline -- \
  --ip "狗1" \
  --image-prompt "a cute dog character, cinematic lighting" \
  --video-prompt "the dog waves happily to the camera" \
  --video-model wan26 \
  --duration 5

Key Files

• src/core/piclumen-client.js: core client and grouped API collection
• src/cli/cli.js: CLI entry point
• src/core/pipeline.js: local pipeline
• shared/client-factory.js: client and API factories
• piclumen-integration-guide.md: integration research notes
• piclumen-model-catalog.md: model catalog snapshot

Security Notes

• Never commit piclumen-auth.json
• Never commit .env or real tokens
• Never expose credentials in issues, screenshots, or logs
• Run a local secret scan before publishing changes

See SECURITY.md for more details.