OPERATIONS GUIDE / 01-08

Image2 Guide

Start with an existing gateway Base URL and API key, then turn natural-language goals, references, paid calls, and generated versions into an inspectable desktop workflow.

STEP / 01

Install the desktop build

Download the package for your system only from GitHub Releases. Current builds are unsigned, so macOS or Windows may show a security warning. Verify the filename and SHA256SUMS on the release page before continuing.

Keep it off the websiteNever paste an API key, conversation, private reference, or generated result into the marketing site. Those belong only in the desktop app and the gateway you configure.

STEP / 02

Connect an OpenAI-compatible gateway

The first launch opens Gateway settings. Enter the HTTPS Base URL, API key, agent protocol, agent model, and image model. The default image model is gpt-image-2; the agent and image calls use the same Base URL and key.

Image2 Studio dark gateway settings screen — The Base URL and API key are configured together. The key field clears after saving.

BASE URL: Remote gateways must use HTTPS; only localhost may use HTTP.
API KEY: The Rust backend stores it in macOS Keychain or Windows Credential Manager.
PROTOCOL: Choose Responses API or Chat Completions to match the gateway.
MODEL: Use the exact model names made available by the gateway.

STEP / 03

Generate the first image

State the subject, use, aspect ratio, visual direction, and invariants. The agent proposes image tasks first. Review titles, prompts, dimensions, and reference relationships before the tasks enter the queue.

Image2 Studio conversation, references, and serial task workspace — Conversation, references, queue state, and versioned results share one work surface.

Create a square product photograph of an unbranded black desktop speaker.
Use a mineral plinth and restrained cyan edge light. No copy, logo, or watermark.

STEP / 04

Give every reference one job

Do not say only “use these references.” Identify which image controls identity, product structure, pose, composition, material, palette, or style, and state the priority when references conflict.

Identity: preserve facial structure, age, hair, and distinctive features.
Structure: preserve product proportions, component placement, and buildable relationships.
Composition: transfer position, camera direction, and negative space only.
Style: transfer light, color, and medium without replacing the subject.

STEP / 05

Constrain local changes with annotations

Continue from an existing version and mark only the area that should change with points, boxes, arrows, or paint. Annotations are location instructions, not output content; everything outside them should stay stable.

Region boxes, arrows, and edit instructions over a mooncake poster — Regions and marks compile into the edit request and must not remain in the result.

STEP / 06

Keep paid calls strictly serial

Image2 runs one image task at a time. Stop prevents the next task from starting; resume continues from the waiting item. Failed tasks retain parameters and errors so you can check quota, model names, and endpoint support before retrying.

Cost boundaryAgent planning and image generation can both consume gateway credit. Review the number of proposed tasks before starting the queue.

STEP / 07

Continue from any version

Every result keeps its parent relationship. Rename a version, hide an unused result, branch from an older image, or place the current version back into the edit context. Hiding does not break files or lineage.

STEP / 08

Troubleshoot the failing stage

401 / 403: Check the key, gateway permission, and model access. Never paste the key into a web page or Issue.
404: Check the Base URL, its /v1 path, and whether the chosen protocol endpoint exists.
429: Wait for quota to recover. Keep execution serial instead of opening parallel windows.
INVALID JSON: The agent response did not match the task contract. Switch to a supported model or protocol.

Use GitHub Issues for public bug reports. Include reproducible steps and redacted errors, never keys, full gateway responses, or private images.