# Nonelinear Image > Generate, edit, or fuse images through NoneLinear from a shell-capable agent, or answer NoneLinear image-model parameter, historical price, latency, and size comparison questions from bundled references. Use for image creation or transformation requests involving NoneLinear, including local references, transparent backgrounds, model selection, dimensions, price, or latency. - Skill: `fitnessnlp/nonelinear-image` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add fitnessnlp/nonelinear-image` - Raw SKILL.md: https://api.skillmd.com/api/skills/fitnessnlp/nonelinear-image/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Fitnessnlp (https://skillmd.com/u/fitnessnlp) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/fitnessnlp/nonelinear-image --- # NoneLinear Image Generate or transform images by running the bundled dependency-free Node.js script. Do not call the `nonelinear` or `nl` CLI, and do not use the host agent's built-in image generator for a NoneLinear request. ## Workflow 1. Treat an explicit request to generate or transform an image as authorization to make one billable API request. Do not make an API request when the user only asks about capabilities or setup. 2. Select the operation from the user's intent: - `generate`: no reference images. - `edit`: exactly one local image path or public HTTPS reference image URL. - `fuse`: at least two local paths or public HTTPS reference image URLs. 3. Extract the prompt and optional model, aspect ratio, size, quality, and count. If the user asks for a transparent image, apply the transparent-image preset below. For `gpt-image-2`, quality defaults to `low` unless the user requests another supported value. 4. Default other requests to `gemini-2.5-flash-image`. Always request URL output. 5. Read [references/models.md](references/models.md) and, when exact limits matter, [references/model-capabilities.json](references/model-capabilities.json) before selecting a non-default model or adding model-specific parameters. Never invent a model ID or unsupported parameter. 6. Locate `scripts/generate-image.mjs` relative to this `SKILL.md` and invoke it with Node.js 18 or newer. In Claude Code, `${CLAUDE_SKILL_DIR}` is the skill directory. In other hosts, use the absolute directory from which this skill was loaded. 7. Parse the single JSON object written to stdout. Claim success only when `status` is `completed` and `images` contains at least one `url` field. 8. Return image URLs as clickable links. Never return or display base64 image data. ## Parameter and Benchmark Queries When the user asks only about model parameters, price, latency, dimensions, or comparisons: - Run `scripts/query-image-models.mjs`; do not load the full registry or benchmark snapshot into Agent context. The query script reads bundled JSON only and does not access the network or API keys. It does not incur an image-generation charge, although normal host-model usage still applies. - For a vague value question such as "which image model is cost-effective", assume `generate`, one image, about `1k`, `1:1`, and cost-first. State these assumptions instead of asking for exact pixels. Treat `1k` or `2k` as resolution and `1:1` as aspect ratio; they are not interchangeable. - Run the default comparison with: ```bash node "/scripts/query-image-models.mjs" benchmark \ --operation generate --resolution 1k --aspect-ratio 1:1 --sort cost --limit 3 ``` - Query selected model parameters without reading the full registry: ```bash node "/scripts/query-image-models.mjs" capabilities \ --models "gpt-image-2,gemini-3.1-flash-image-preview" ``` - Describe "cost-effective" only in terms of historical cost and latency. The bundled data has no quality score, so do not claim an overall value or quality winner. - Keep the default answer compact: show at most three ranked records per comparison group, then one short conclusion. Do not paste the query script's raw JSON. - Filter by `operation` first: `generate` is text-to-image and `edit` is single-image editing. The snapshot has no multi-image fusion price data. - Keep each returned `comparison_group` separate. Never merge exact `1024x1024` requests with models that produced an observed 1K square through a tier, aspect ratio, or provider default. - Keep `request_size` and `actual_size` distinct. An observed output size does not prove that a model accepts an exact pixel-size parameter. - Include `data_version`, `as_of`, and currency. Present `zero_cost_observations` separately as unconfirmed historical observations, not ranked recommendations or free models. - Omit source columns. Only when the user explicitly asks for price provenance, rerun with `--include-cost-source true` and explain that it is internal historical provenance. - When no comparable group exists, including current 2K or fusion price queries, say that the bundled data is insufficient. For 2K, run `capabilities --operation generate --resolution 2k` to list parameter support but do not construct a price ranking. - Treat `configuration_label` as a display label, not a model ID. For example, `gpt-image-2-low` means `model=gpt-image-2` with `quality=low`. ## Transparent Images Treat any request for a transparent image, transparent background, cutout, or no background as transparent-output intent. The user does not need to name API parameters. Internally: - Use `gpt-image-2`. - Pass `--background transparent` and `--output-format png`. - Ensure the prompt explicitly requests a transparent background. Add that wording when the user's intent is clear but the prompt does not already contain it. - Exclude the scene, floor, base, reflection, and shadow when the user wants a clean cutout. Do not claim that the model lacks transparency based only on a preview background. Validate the downloaded original PNG's alpha channel when verification is required; image viewers may display transparent pixels as white or a checkerboard. When the user gives a local image path, pass that path string directly to `--image-file`. Do not use `Read`, attach the image, inspect it, or encode it in the agent. The child script reads and base64-encodes the file in its own process, uploads it to the fixed NoneLinear upload endpoint, and passes only the returned URL to the image API. Base64 bytes never enter stdout or the model context. ## Script Invocation Text-to-image with the defaults: ```bash node "/scripts/generate-image.mjs" \ --prompt "白色陶瓷马克杯放在胡桃木桌面上，清晨自然光，真实摄影风格" ``` Specify supported options only when requested or required by the chosen model: ```bash node "/scripts/generate-image.mjs" \ --model "gemini-2.5-flash-image" \ --prompt "未来城市天际线，电影感广角摄影，日落自然光" \ --aspect-ratio "16:9" \ --response-format "url" ``` Edit one image: ```bash node "/scripts/generate-image.mjs" \ --operation "edit" \ --image "https://example.com/source.png" \ --prompt "把背景替换为浅灰色摄影棚，保留主体不变" \ --aspect-ratio "1:1" ``` Edit a local image without loading it into agent context: ```bash node "/scripts/generate-image.mjs" \ --operation "edit" \ --image-file "/absolute/path/to/source.png" \ --prompt "把背景替换为浅灰色摄影棚，保留主体不变" ``` Fuse multiple images by repeating `--image` in the intended reference order: ```bash node "/scripts/generate-image.mjs" \ --operation "fuse" \ --image "https://example.com/product.png" \ --image "https://example.com/scene.png" \ --prompt "把图一的产品自然放入图二的场景，保持产品外观" ``` Local files and URLs can be mixed. Preserve their command-line order: ```bash node "/scripts/generate-image.mjs" \ --operation "fuse" \ --image-file "/absolute/path/to/product.png" \ --image "https://example.com/scene.png" \ --prompt "把图一的产品自然放入图二的场景，保持产品外观" ``` Use `quality` and `size` with `gpt-image-2`: ```bash node "/scripts/generate-image.mjs" \ --model "gpt-image-2" \ --prompt "白色陶瓷马克杯产品图，浅灰摄影棚背景" \ --size "2048x1152" \ --quality "high" ``` Generate a transparent PNG with `gpt-image-2`: ```bash node "/scripts/generate-image.mjs" \ --model "gpt-image-2" \ --prompt "一瓶高端植物精华液概念瓶，主体完整，透明背景，不要场景、地面、底座、投影和倒影" \ --size "1024x1024" \ --background "transparent" \ --output-format "png" ``` Use Seedream 5 Pro for text-to-image: ```bash node "/scripts/generate-image.mjs" \ --model "doubao-seedream-5-0-pro-260628" \ --prompt "透明玻璃茶壶放在胡桃木桌面上，1:1 构图，真实产品摄影" \ --size "1K" \ --output-format "png" \ --watermark "false" \ --optimize-prompt-mode "standard" ``` Supported script arguments: - `--prompt `: required. - `--operation `: optional; inferred from the reference image count when omitted. - `--image `: repeat for each reference image; preserve the user's order. - `--image-file `: repeat for local references; may be mixed with `--image` in order. - `--model `: optional; defaults to `gemini-2.5-flash-image`. - `--aspect-ratio `: optional; for example `1:1` or `16:9`. - `--size `: optional; use only for a model documented to support it. - `--quality `: optional and valid only for `gpt-image-2`; this Skill defaults it to `low`. - `--n `: optional integer from 1 through 10; omit when the model does not support it. - `--response-format `: optional compatibility argument; only `url` is accepted. - `--output-format `: model-specific; read the capability registry before use. - `--background `: `gpt-image-2` generation only. - `--watermark `: Seedream 5 Pro and Qwen 2.0/3.0 models only. - `--optimize-prompt-mode `: Seedream 5 Pro only. - `--negative-prompt `: Qwen 2.0/3.0 models only. - `--prompt-extend `: Qwen 2.0/3.0 models only. - `--prompt-extend-mode `: Qwen 3.0 models only; `agent` is generation only. - `--enable-thinking `: Qwen 3.0 models only; requires prompt extension. - `--seed `: Qwen 2.0/3.0 models only. Do not pass the API key as a command argument. Do not construct the request with `curl` or an ad hoc script; the bundled script enforces endpoint and output safety. For the default model, use no more than three reference images. Pass each URL or local path string directly to the script. Do not use `Read`, WebFetch, `curl`, browser tools, or another command to fetch, inspect, download, or base64-encode an input image before calling the script. ## Context Safety Keep image bytes outside the agent context: - Never attach local image bytes to a tool call for this workflow. - Never put base64, a data URL, or binary image content in the prompt, command, stdout, or reply. - Pass local references as path strings with `--image-file`; the child process handles upload. - Base64 exists briefly only inside the child process and the upload HTTP body. It is never printed, returned, logged, or passed back through the agent. - If the user already attached an image to the conversation, explain that the host may already have counted that image against context before this Skill ran; the Skill cannot remove it. - If the API unexpectedly returns only `b64_json`, report `base64_output_blocked`. Do not print the payload or retry automatically. For `gpt-image-2`, use `size`, not `aspect_ratio`. Higher `quality` usually increases latency, output tokens, and cost. Read [references/models.md](references/models.md) for complete size constraints before choosing a custom resolution. This Skill currently exposes transparent backgrounds only for text-to-image generation. For `doubao-seedream-5-0-pro-260628`, use `size`, never `aspect_ratio` or `n`. It supports text-to-image, one-image editing, and fusion with up to ten references. Preserve `` and `` tags in prompts. Do not attempt grouped output or pass `sequential_image_generation`; this model does not support it. Its request timeout is 600 seconds. For Qwen and Wan models, read the registry before adding parameters. `qwen-image-3.0` and `qwen-image-3.0-pro` are pending `api/images.mdx` sync, but this Skill applies the documented `qwen-image-2.0` parameter policy to them: `size`, no `aspect_ratio`, up to three reference images, and `n` from 1 through 6. `prompt_extend`, `negative_prompt`, `seed`, and `watermark` have been verified through NoneLinear on Qwen 2.0 and 3.0. `qwen-image-2.0`, `qwen-image-2.0-pro`, `qwen-image-3.0`, `qwen-image-3.0-pro`, `wan2.7-image`, and `wan2.7-image-pro` have passed direct text-to-image smoke tests. `qwen-image-3.0` single-image editing and `qwen-image-3.0-pro` three-image fusion also passed direct API tests. Do not present other editing or fusion paths as verified until a separate reference-image test has passed. In observed NoneLinear responses, Qwen 3.0 requests with `n=2` returned one image URL; do not promise multiple returned images until that behavior is confirmed for the target account/model. `qwen-image-3.0` text-to-image has passed Claude Code host end-to-end verification. ## Credentials The script reads credentials from the child process environment in this order: 1. `NONELINEAR_API_KEY` 2. `Nonelinear_API_KEY` 3. `OPENAI_API_KEY`, only when `OPENAI_BASE_URL` is an HTTPS URL whose exact hostname is `api.nonelinear.com` 4. `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY`, only when `ANTHROPIC_BASE_URL` is an HTTPS URL whose exact hostname is `api.nonelinear.com` Do not read `.env`, cc-switch databases, or Claude/Codex configuration files. Those tools may inject credentials into the agent process environment. If the script returns `missing_api_key`, ask the user to configure an environment variable outside chat. Never ask the user to paste a real key into the conversation. Request destinations are fixed to `https://nonelinear.com/api/upload-file` for local inputs and `https://api.nonelinear.com/v1/images/generations` for image generation. Environment variables cannot redirect them. ## Result Handling Success has this shape: ```json { "status": "completed", "operation": "edit", "model": "gemini-2.5-flash-image", "images": [{ "url": "https://example.com/image.png" }], "request_id": "request-id-or-null" } ``` Failure has this shape: ```json { "status": "failed", "error": "Human readable message", "code": "stable_error_code" } ``` Gemini can return HTTP success with `data: []`, text only, `IMAGE_RECITATION`, or `NO_IMAGE`. Treat all such responses as failure unless an item contains a non-empty `url`. Block a base64-only response instead of emitting it. For `no_image_output`, explain that the provider returned no image and suggest revising the prompt. Do not automatically retry, because each request may incur cost. For `missing_api_key`, give environment setup guidance. For all other failures, report only `error` and `code`; never show request headers, an Authorization value, a complete request object, or credential values. Do not use this Skill for video generation, model listing, general-purpose file uploading, or downloading output files. Local image upload is only an internal preprocessing step for edit and fusion requests.