Reference & troubleshooting

Generation calls the model provider you configured yourself, and the provider bills you for it. This app never collects payment on its behalf, so errors like this almost always come from the provider account.

What to check, in order:

1. Sign in to the provider console and confirm the balance or remaining quota is sufficient (an exhausted free tier fails just the same).
2. Settings → Models: confirm the key is correct, not expired and not revoked.
3. Confirm the models you need are ticked and enabled, and that default text / image / video models are each set.
4. Run the same node with a different model — that separates “an account problem” from “a single-model problem”.

1. Check for stray spaces or line breaks around the key; copying and pasting it again usually fixes it.
2. Confirm the key has permission for the model in question on the provider side — some models require a separate application.
3. If you use a proxy or relay service, make sure the relay address is complete (including the /v1 path and similar).
4. On a restricted network, configure a proxy in settings and retry; HTTPS interception on corporate networks also breaks fetching.

Ports strictly distinguish singular from plural: mismatched types never connect, and singular can't go into plural — image won't go into images, and the same goes for video / voice / text.

Common fixes:

1. When a node needs a list input (e.g. “Select image / video / audio / text”), connect from the upstream square port (out-all, or out-shots / out-actions on the director stage); the default round out won't connect.
2. Structured directory ports use world / worldEntities / beat (world elements / world element entities / shot) and must not be mixed with plain text.
3. A script node's text also can't go straight into “Select text” — use the matching list port.

See §8 Node graph.

1. Open the node's run log and read the actual error (most of the time the model returned an error or a parameter was invalid).
2. Confirm upstream nodes ran successfully: if upstream never finished, downstream has no input.
3. Check whether the task queue is saturated by another long job; pause or cancel queued tasks.
4. Gallery generation nodes have two outputs, out (currently selected) and out-all (whole history). If you wired out, check in the Inspector that the item you expect is selected.

This is the classic trap of pure text-to-image. Solve it with references rather than repeating descriptions:

1. Use anchor images: split reference images out of a 9-grid / 4-grid sheet cell by cell, then feed them in as references for later generations to lock face, outfit and setting.
2. Register characters, scenes and props as world elements so every shot shares one description instead of re-describing them each time.
3. Check whether a node in the middle switched models or heavily rewrote the prompt — style drift usually comes from there.
4. In the short-drama flow, make good use of the review1~review4 review nodes to send sub-par results back in time.

See §2 Core concepts and the Short-Drama Guide.

1. Append an HD upscale node at the end of the generation chain; the short-drama template already includes that step.
2. Check the resolution setting on the generation node — some models need an explicit size.
3. Avoid over-compression: watch the scale factor and export format when exporting.

1. Confirm the motion prompt is filled in properly; a static description produces an almost static shot.
2. Confirm the chosen video model supports the target duration and resolution.
3. Reference videos need a publicly reachable URL: configure object storage (TOS / OSS / COS / Amazon S3–compatible, only one enabled at a time). You can skip it for purely local previews, but reference-video features will be limited. For the S3 fields, see the Yandex Object Storage example.
4. See the Video Tutorials.

1. Only one object storage can be enabled at a time (Volcengine TOS / Alibaba Cloud OSS / Tencent Cloud COS / Amazon S3–compatible) — disable the old one before enabling a new one.
2. A private bucket can stay private. With the public base URL left empty, the app issues a signed link valid for about 24 hours that models can fetch; upload again after it expires.
3. Verify the AccessKey has read / write permission on that bucket and that the region is correct. Yandex Object Storage uses region ru-central1 — see the setup example.
4. Fill in a public base URL only when you want a stable public address. Chinese CDN domains still need ICP filing when the provider requires it.

1. Confirm comfy-api-proxy is running locally and that the port matches the one configured in the app.
2. Confirm ComfyUI itself is running and reachable.
3. You must use an API-format workflow (enable Dev Mode in ComfyUI and export with “Save (API Format)”); the UI format (which contains nodes / links arrays) won't work.
4. See the ComfyUI guide.

1. Confirm the installer matches your system architecture (on macOS, Intel vs Apple silicon).
2. If the first launch is blocked by system security policy, allow the app to run in System Settings.
3. If an update fails, re-check under Settings → General → About & updates, or download the release manually and install over it.
4. If it still misbehaves, back up your project directory, reset the configuration and retry — and remember to attach logs and your OS version when reporting.

The app ships with an MCP tool service. Once connected, Claude Code and other AI agents can plan workflows, edit node graphs, run generations and query tasks from a chat. The app must be running first. Pick either of the two methods:

1. stdio bridge (recommended, needs Node.js 18+): run claude mcp add aiartengine -- node <install-dir>/resources/mcp-bridge.mjs.
2. HTTP direct (no Node.js needed): open Settings → MCP and copy the “Claude Code connection command”, or run it manually as claude mcp add --transport http aiartengine <endpoint> --header "Authorization: Bearer <token>" (endpoint and token live in the app-side mcp.json and persist across restarts).

After registering, restart the agent session for the tools to appear. The app-side mcp.json (%APPDATA%/aiartengine/mcp.json) is maintained by the app — do not edit it by hand. If the register command errors (e.g. Script not found), your Claude Code install is usually broken — reinstall and retry. Full steps and the tool list: MCP guide.

1. Model unavailable (HTTP_404 etc.): the chat panel uses the text model selected in the model dropdown — the model ID must match a name that actually exists at the chosen provider; switch to a model enabled on your provider account or to another provider whose key you've configured.
2. No model selected / none available: first enable at least one text model with its key under Settings → Models.
3. Spinner never ends: make sure Node.js ≥ 22.19 on this machine (installers bundle the runtime); watch the panel status line and logs.
4. Tool execution failed: check the error on the tool card — usually the project isn't open or the API key ran out of quota.