AI Art Engine 中文
Menu

Manual · Setup

Projects & settings

Create and open projects, then configure general preferences, model providers, object storage, extensions, the MCP tool service and web search. Walk through this part first when you set up the app.

3. Home & projects

Create a project

  1. Click New Project.
  2. Fill in the project name.
  3. Click Browse to choose the storage directory.
  4. Click Create to enter the workspace.

Open a project

  • Click Open Project and pick project.json inside the project directory.
  • Or click a path in the Recent projects list.

Recent projects

  • The list shows project paths you opened recently.
  • The × on the right means “remove from the recent list” — it does not delete the project files on disk.
This release has no in-app “Delete project” action. To remove a project entirely, delete its folder in your file manager.

4. Settings

Open Settings from the home page or the workspace top bar. Changes are saved automatically.

4.1 General

  • Theme: dark / light.
  • Language: 中文 (Chinese) / English.
  • Auto save: can be enabled, with an interval in seconds.
  • About & updates: view the version and check for updates (see below).

4.2 Models

  1. Click Add model provider. Options include:
    • OpenRouter: text / image / video / decisions (aggregated catalog, single API Key).
    • OpenAI: text (GPT family) / images (gpt-image-1 / gpt-image-2); requires network access to api.openai.com and a non-mainland account. Text-to-image uses /images/generations, reference-image editing uses /images/edits (1 image max).
    • DeepSeek: text only (deepseek-chat / deepseek-reasoner, OpenAI compatible).
    • Zhipu: GLM text (/chat/completions) + CogView text-to-image (glm-image / cogview-4 / cogview-3-flash, /images/generations).
    • Kimi (Moonshot): text (kimi-k2 series / moonshot-v1 series, OpenAI compatible, default Base URL https://api.moonshot.cn/v1).
    • xAI (Grok): text (grok-* chat, OpenAI compatible, default Base URL https://api.x.ai/v1) + Grok Imagine text-to-image (/images/generations, JSON body, supports aspect_ratio) + Grok Imagine Video async video (/videos/generations submitted then polled at GET /videos/{request_id}; 480p / 720p, 5–15s, first-frame image-to-video).
    • Google (Gemini): text (gemini-* chat) + Nano Banana text-to-image / image-to-image (/images/generations, JSON body, supports aspect_ratio / resolution / n / response_format and image reference fields) + Veo 3.1 async video (/videos submitted then polled at GET /videos/{id}; 720p–4K, 4–8s, first-frame image-to-video) — all through the official OpenAI compatibility layer (default Base URL https://generativelanguage.googleapis.com/v1beta/openai).
    • vLLM: local OpenAI-compatible service (default http://localhost:8000/v1), no API Key required; deploying vLLM-Omni diffusion models (e.g. Wan2.2 T2V / I2V) enables video generation (async jobs on /v1/videos, can carry a first-frame image).
    • Ollama: local OpenAI-compatible endpoint (default http://localhost:11434/v1), no API Key required.
    • LM Studio: local OpenAI-compatible endpoint (default http://localhost:1234/v1), no API Key required.
    • Volcengine Ark: text / Seedream images / Seedance video use the Ark API Key; sound design goes through Doubao Speech openspeech (a Speech console API Key, which can differ from the Ark Key) plus a manually entered speaker_id. Video models include Seedance 2.5 (doubao-seedance-2-5-260628: up to 30s per request, 50 omni references, timestamp-level segment editing) plus Seedance 2.0 / 2.0 Fast.
    • Kling: images / video (API Key).
    • MiniMax: text / image / video / voice design (same API Key; default Base URL https://api.minimaxi.com).
    • Tongyi Qianwen: text (compatible mode) / Wanxiang images / Wanxiang video (including HappyHorse, Wan 3.0-Video, …; Bailian API Key). Wan 3.0-Video supports 30s per request with 10 image + 5 video + 5 audio references; it is in public / invite beta, so use the Model ID from the Bailian console.
    • ModelScope: text / text-to-image (ModelScope access token, e.g. ms-…).
    • ComfyUI: images / video / audio via API 2 (POST /api/v2/jobs). The model id is the API-format workflow name in userdata (not a checkpoint), and the model list is pulled from the service dynamically. Video workflows support multimodal references (r2v), video / audio reference injection and first/last frame injection (first_frame / last_frame), with a 15s duration cap. The default local Base URL is http://127.0.0.1:8189 (install comfy-api-proxy first — don't connect to 8188 directly); for the cloud enter https://cloud.comfy.org plus a key. The key can be empty locally. Full steps: ComfyUI guide.
    • MagicRouter: multi-provider aggregation gateway (OpenAI compatible), text / image / video; requires an API Key starting with mr-, default Base URL https://api.magicrouter.ai/v1, model catalog from /models/live, video submitted async then polled.
    • Meshy: text-to-3D / image-to-3D (including multi-image to 3D; API Key; default Base URL https://api.meshy.ai).
    • Tripo: text-to-3D / image-to-3D (API Key; default Base URL https://api.tripo3d.ai).
    • Rodin (Hyper3D): text-to-3D / image-to-3D (API Key; default Base URL https://api.hyper3d.com/api/v2).
    • Luma AI: text-to-3D / image-to-3D (API Key; default Base URL https://api.lumalabs.ai/dream-machine/v1).
    • Lux3D: text-to-3D / image-to-3D / multi-image to 3D (API Key; G1 / G1-Turbo; default Base URL https://api.aholo3d.cn).
    • World Labs (Marble): spatial world generation — text-to-world / image-to-world / multi-image to world / video-to-world (API Key; default Base URL https://api.worldlabs.ai, auth header WLT-Api-Key; models marble-1.1, marble-1.1-plus, plus the previous-generation marble-1.0 and marble-1.0-draft. Reference media uses the official managed upload, so no object storage is needed).
    • Custom: pick an endpoint type (OpenAI compatible / Anthropic / Gemini) and supply your own Base URL and API key — for relays such as NewAPI and one-api, or a self-hosted service. Text and images are supported, and models often cannot be fetched from the catalog, so you type their ids by hand — see the NewAPI guide for the full walkthrough.
  2. After selecting or expanding a provider, the settings page links to its key request page (you can also open these directly):
  3. Enter a display name, Base URL and key (which can be shown or hidden).
  4. After enabling the provider, click Fetch models (Kling / some MiniMax modalities / Bailian image & video / OpenAI and Zhipu images use local static catalogs; local services such as vLLM / Ollama / LM Studio / ComfyUI need no key and are fetched directly).
  5. Use filters plus select-all / clear to tick the models you want; model IDs can also be added manually.
  6. Configure per modality: text / image / video / audio / 3D model / spatial world / decisions (OpenRouter supports text / image / video / audio / decisions; its Decisions tab lists models via output_modalities=decisions. TypeSafe direct has a Decisions tab only — its catalog comes from GET /v1/models and judgements go to POST /v1/systemone, the same decision protocol as OpenRouter but without the hop. The Ark audio tab also links the speech console and asks for a manual speaker_id; Kling has only image and video tabs; MiniMax supports text / image / video / voice design; OpenAI supports text / image / audio; ElevenLabs exposes both the Audio and Music tabs (speech synthesis / multi-speaker dialogue / sound effects live under Audio, music generation under Music); DeepSeek is text only; Kimi (Moonshot) is text only; xAI (Grok) supports text / image / video with async polling for video; Google (Gemini) supports text / Nano Banana images / Veo 3.1 video with async polling; Zhipu supports GLM text and CogView images; vLLM supports text and video (Wan T2V / I2V); Ollama / LM Studio are text only, though multimodal understanding can pass images into text nodes; ModelScope supports text and image with async text-to-image jobs; ComfyUI supports image / video / audio and has no text tab; MagicRouter supports text / image / video; Meshy / Tripo / Rodin (Hyper3D) / Luma AI / Lux3D only expose a 3D model tab, while World Labs (Marble) only exposes a spatial world tab; a custom provider's tabs follow its endpoint type — OpenAI compatible / Gemini give text + image, Anthropic gives text only, and image models must always be typed in by hand (see the NewAPI guide).
  7. Audio (TTS): the audio tab on OpenAI and OpenRouter posts to POST /audio/speech with a body of model + input + voice (optional response_format / speed) — the OpenAI TTS protocol shape that aggregators (new-api / one-api / self-hosted gateways) implement, so pointing the Base URL at a gateway works as-is. Catalog: OpenRouter uses /models?output_modalities=speech (which carries supported_voices), while OpenAI uses a local static table (GET /models returns ids without voice lists); aggregator-only models can be typed in by hand. ElevenLabs speaks its own protocol: POST /v1/text-to-speech/{voice_id} (auth header xi-api-key), with models from GET /v1/models and voices from GET /v1/voices. Its voice_id is an opaque string, so the panel shows voice names instead (e.g. Sarah - Mature, Reassuring); the voice catalog is publicly readable, so you can browse models and voices before setting a key. The same key also powers two existing pipelines: speech-to-text (Scribe, the timeline's “audio to subtitles”) and music generation (BGM / SFX). All three share one model catalog; the voice node's dropdown lists TTS models only. The voice is set in the voice node's instruction panel, not here: it is a per-node parameter, so different voice-over nodes in one graph can use different voices. Suggestions come from the supported_voices returned by the API (OpenRouter's docs page does not list them, but /models?output_modalities=speech returns them — 18 of 23 speech models in a live check, with Microsoft MAI Voice carrying 97), sorted so your app language comes first. Leaving it empty uses the model's own default — we never guess a voice name for the upstream, because voice naming is not portable. A few models (e.g. bytedance-seed/seed-audio-1-0) have no voice list at all: their voice comes from the prompt text, so just leave it empty.
  8. Two more audio nodes (ElevenLabs-specific endpoints; both produce voice assets):
    • Multi-speaker dialogue: synthesises a whole conversation in one call. Write one utterance per line as Speaker: line (either colon style works), e.g. A: You finally made it. / B: Traffic was awful.. Lines without a colon keep the previous speaker (narration / monologue). Bind a voice per speaker in the node's instruction panel (unbound speakers fall back to the node's default voice); a missing voice reports exactly which line and speaker.
    • Sound effect: uses POST /v1/sound-generation and describes the sound itself (e.g. "rain on a tin roof"), not a spoken line. The instruction panel offers “seamlessly loopable” (turn it on for long-playing ambience — no more clicks at the loop seam), “expected duration” (spec range 0.5–30 s) and “prompt influence” (0–1, default 0.3); the file lands in Cache/Sfx. That endpoint's model is a single fixed value (eleven_text_to_sound_v2), so the dropdown on the card actually picks which provider instance to use (only meaningful with multiple accounts / keys) — its title already says “model is fixed to …”. With no provider available it errors out explicitly instead of falling back to speech synthesis.
    Both reuse the same ElevenLabs key as “audio to subtitles”.
  9. Music (BGM) lives on its own tab: ElevenLabs' POST /v1/music is filed under the Music tab (kept separate from Audio) — music is composition (prompt + lyrics / instrumental) while speech synthesis is TTS (text + voice), and the two use different endpoints and model families. The same tab also lists music models from OpenRouter (Google Lyria 3), MiniMax (music-3.0) and DashScope (fun-music-v1); the music node's dropdown lists music models only and never shows TTS models. Settings that stored music models under the Audio tab are migrated automatically.
  10. Set the default generation model if needed. Provider cards can be collapsed to save space.
API Keys are stored in a local settings file (Windows example: %APPDATA%\AIArtEngine\aiartengine-settings.json) and are never uploaded to any official server.

4.3 Object storage

Used to upload local files such as reference videos into publicly reachable URLs (signed links are used for private buckets).

  • Add object storage → pick one:
    • Volcengine TOS: AccessKey / SecretKey, Region, Endpoint, Bucket.
    • Alibaba Cloud OSS: AccessKey / SecretKey, Region, Endpoint, Bucket.
    • Tencent Cloud COS: SecretId / SecretKey, Region, Bucket (usually BucketName-APPID).
    • Amazon S3–compatible: Endpoint, Region, Access Key, Bucket. See the Yandex Object Storage example for the field-by-field setup. Cloudflare R2, Backblaze B2, Wasabi, MinIO and Amazon S3 use the same form.
  • Key request pages (also linked inside settings):
  • A public access domain (CDN / custom domain) is optional; when it's empty, signed URLs are used (valid for about 24 hours).
  • Only one object storage can be enabled at a time — enabling one automatically turns off the others. Cards can be collapsed.

Configure Amazon S3–compatible storage with Yandex Object Storage

Amazon S3–compatible speaks the standard Amazon S3 API (Signature V4). The walkthrough below uses Yandex Object Storage. Cloudflare R2, Backblaze B2, Wasabi, MinIO, DigitalOcean Spaces and Amazon S3 itself use the same form — only Endpoint, Region and path-style change.

  1. Create an Object Storage bucket in the Yandex Cloud console. See Create a bucket.
  2. Create a service account and grant it the storage.editor role. The app both uploads and deletes objects, and this role covers both.
  3. Create a static access key for that service account and save the Access Key ID and Secret. The Secret is shown only once. See static access keys.
  4. Back in the app: Settings → Object storage → Add object storage → Amazon S3–compatible.
  5. Fill in the fields below and enable the provider.
Field Yandex Object Storage
Endpoint https://storage.yandexcloud.net
Region ru-central1
Access Key ID Key ID from the static access key
Secret Access Key Secret from the static access key
Bucket name The bucket created above
Path-style requests Leave on
Public base URL (optional) Leave empty for a private bucket; fill in for a public bucket or a custom domain
Set Region to ru-central1. The placeholder us-east-1 is an Amazon S3 example; leaving it in place for Yandex makes the signature fail.

With path-style left on, object URLs look like https://storage.yandexcloud.net/<bucket>/<key>. Bucket names that contain a dot (for example example.ru) use this same URL for HTTPS.

Leave the public base URL empty and a private bucket gets a signed link valid for about 24 hours, which models can fetch directly. When the bucket is public, or you have bound your own domain, fill in the public base URL, for example https://<bucket>.storage.yandexcloud.net.

For another Amazon S3–compatible service, keep Amazon S3–compatible and change only these three fields:

Service Endpoint Region Path-style
Amazon S3 https://s3.amazonaws.com, or the regional endpoint from the console The bucket region, such as us-east-1 Off
Cloudflare R2 The S3 API endpoint from the dashboard auto Off
MinIO Your server, such as https://minio.example.com Whatever the server uses, often us-east-1 On

4.4 Extensions

In-app extensions run on Cordis (ctx.editor.*) and can contribute nodes, cards, inspectors, skills and executor overrides; see GRAPH_PLUGINS.md in the repository for development notes. The settings page only lists declarative extensions under the plugins folder in the user data directory. Arbitrary external scripts are never executed — only declared extension information is shown. Official installers don't load the “graph plugin sample” demo.

4.5 MCP tool server

The app embeds an MCP tool server for external AI agents such as Claude Code / Codex (and the built-in AI chat panel) — plan & commit workflows, run generation, read/write assets and node graphs. See the MCP setup guide for full steps.

  • Start / restart: the settings page shows run state and port; the default port is 43110, falling back through 43110–43119 when busy. Changing the port or clicking “Restart” brings the server back on the new port.
  • Token: view / copy / edit are supported; it persists across restarts, so configure once. Click “Reset token” if you suspect a leak — the old token is invalidated immediately and clients must re-register with the new one.
  • Connect command: one-click copy of the claude mcp add --transport http … command; run it in a terminal to register the app as a Claude Code MCP server (HTTP direct, no Node.js needed).
The tool server only listens on 127.0.0.1 loopback and every request needs a Bearer token; file access is confined to the project root; every tool call is appended to the audit log <userData>/logs/mcp-audit.jsonl (5 MB rolling).

The settings panel also lets you configure the stdio bridge visually: change the bridge command (default is still node + the in-repo scripts/mcp-bridge.mjs or the installer's bundled <install dir>/resources/mcp-bridge.mjs), the bridge HTTP port, the Blender addon host / port passthrough (BLENDER_HOST / BLENDER_PORT). Changes persist immediately; external agents just reconnect — no app restart needed.

The same panel supports a “reverse bridge”: register any external stdio MCP server (such as the Blender addon or any local MCP service) so the in-app ◈ AI chat panel (DeepSeek Harness / dsh) can consume its tools directly — no need to expose a separate socket port. See the MCP setup guide, reverse-bridge section.

Third-party MCP servers (remote HTTP or local stdio commands) can also be added and managed from the MCP tab of the plugin marketplace.

Settings → Web search tab configures multiple providers running side by side. Deliberately split from the model provider system — fewer adapters, no per-project context injection needed; the module-level registry is sufficient, and it can be migrated to a Cordis plugin cleanly once a flood of third-party search services shows up.

Mock always returns the same fixed payload — useful in offline dev and CI to flip the “search available” bit without a real network call. Don't enable it in production (it can fall through when other providers are off, but never replaces real data).