Image Generation

Image Generation

ChatHub's Image workspace creates and manages AI-generated images at /image. It is available in server-mode deployments when the ai_image feature is enabled.

The Image workspace already backgrounds jobs through async_tasks. That is separate from background conversation generation. If a chat model would call an image tool (DALL·E and similar), ChatHub defers the whole conversation turn to the connected browser instead of faking a server image result.

Stay on that chat until the Image tool cards appear. After the cards are there, switching topics does not Stop generation: the pictures still land on the original topic while this tab stays open. Leaving during Deep Thinking on iPhone/Safari can abort the stream (Load failed) before any cards appear; send again if that happens.

Open Image

• On desktop, select Image in the left navigation.
• On mobile, select Image in the bottom navigation.

Discover is no longer a primary desktop or mobile action. Existing direct links remain available for compatibility.

Create an image

1. Open Image Settings and select an available provider and model.
2. Adjust the supported model options and choose an image count from 1 to 50.
3. Enter a non-empty prompt.
4. Select Generate.

On desktop, settings stay in the left panel. On mobile, the sliders button in the header opens settings in a bottom drawer so the workspace remains usable on small screens.

All Image Settings controls share one normal scroll flow. Number of Images is the final setting after the model's supported reference image, Size, Quality, dimension, Steps, CFG, and Seed controls. It scrolls with the rest of the form on mobile and desktop instead of staying over other settings.

There is no separate Image destination in application Settings. Choose the count directly with Number of Images in the Image workspace.

For signed-in users, ChatHub remembers the selected provider, model, image count, and any supported Size option and syncs them to the account, so the same settings follow the user across devices (for example, desktop browser and an installed mobile app). Changes are saved in the same order they are made, and the latest account setting takes precedence over older account settings. Browser settings saved while signed out remain guest-only and are not automatically copied into an account. Historical browser values from older ChatHub versions may have been written while another account was active, so assigning them automatically could copy one user's provider/model choice into another account. An account without a remembered image count starts from the deployment's AI_IMAGE_DEFAULT_IMAGE_NUM value, or 4 when the variable is not set.

When the user is not signed in, these settings are remembered only in the current browser. Signing out restores any guest settings saved in that browser before or after using an account; otherwise ChatHub starts from the current defaults. Signing back in restores only that account's settings. Switching directly to another account keeps image generation unavailable until both that account's settings and provider/model configuration are ready. It also clears the previous account's chat sessions, messages, image history, drafts, and agent configuration while the new account loads. The new account uses current defaults when no saved image settings exist, instead of showing or retaining the previous account's model, count, Size option, enabled models, provider credentials, or conversation data.

If a saved model or Size option is no longer available, ChatHub uses an available model and its current defaults instead while retaining a valid saved image count. A prompt typed while settings are loading is preserved. If enabled providers, models, or supported options change while the app is open, ChatHub revalidates the active settings. A disabled model switches to an available usable model, and options that the updated model no longer supports reset to that model's current defaults. Models that use width, height, or aspect ratio instead of a Size option keep those unsaved edits during ordinary image-count and availability revalidation. Models whose generation settings cannot be loaded are hidden from Image Settings and skipped when ChatHub chooses a fallback. If a provider has no usable image models, its model list shows guidance to review that provider in Settings.

If no usable image model is enabled, Image Settings shows the provider/model guidance instead of remaining in a loading state. Generation stays disabled until an image provider and usable model are enabled in Settings. If the previously remembered model later becomes usable, ChatHub restores it before choosing another enabled model.

If the active account settings or provider/model configuration cannot be loaded, Image Settings replaces the loading indicator with an error and Retry. On mobile, retry runs inside the open bottom drawer; the drawer does not need to be closed and reopened. A successful retry shows the normal controls in place. If retry fails again, the error returns without displaying settings or credentials from another account. If the signed-in session returns a different account, ChatHub clears the loaded account settings, keeps generation unavailable, and shows Sign in again instead of Retry. Use that command to establish a new authenticated session before continuing. ChatHub also clears provider credentials held in memory and cancels active image, chat, upload, plugin, profile, preference, and settings operations that belong to the invalid session. Cached account lists and histories are removed, and automatic focus or reconnect refreshes remain blocked while the mismatch is active. New account-setting changes are also rejected until sign-in establishes a consistent account. Late responses and queued settings writes cannot restore the invalid account's data or continue changing the workspace. If ChatHub cannot resolve the signed-in account itself, sign in again before reopening Image Settings.

Unreadable browser-only Image preferences do not block the workspace. ChatHub uses current defaults and continues loading account/provider configuration. Denied browser storage and malformed settings left by older releases also do not crash Image Settings during startup.

The prompt is trimmed before submission. ChatHub shows an error message and unlocks the Generate control if topic creation or request submission fails. After a request is accepted, ChatHub opens the Image Topic, clears the submitted prompt, and keeps queued image tiles visible while generation continues in the background. On mobile, task-status updates do not pull the viewport away from those tiles or beneath the prompt. Topic synchronization and thumbnail polling remain active even when the Image Topics drawer has never been opened. New topics are registered under their permanent ID before generation starts, so the topic opens immediately, its title is generated, queued tiles stay visible, and a completed generation fills its thumbnail automatically.

Image topics

Each generation belongs to an Image Topic. Creating an image without an active topic creates one automatically.

• Desktop shows topics in the right panel.
• Mobile opens Image Topics from the list button in the header.

Use topics to switch between generation histories or start a new topic. Automatically generated topic names are stored and displayed as plain text. Current versions also hide surrounding Markdown emphasis left on titles created by older versions.

For durable generated-image browsing, use the top-level Artifacts gallery. Artifacts remain available after an Image Topic is removed. The Image Topics overflow menu also provides manual history housekeeping, which removes topic records and disposable history media while preserving the generated originals. Delete those originals from Artifacts with Select this page and Delete; housekeeping still does not remove them. Gallery deletion also tries to remove unused workspace thumbnails from storage after the database commit.

Manage results and reference images

Generation cards provide actions to download or delete an image, copy/apply a seed when supported, reuse settings, copy a prompt, or delete a batch. These controls are visible on touch devices and do not require hover.

Models that accept reference images expose add, change, upload-more, and delete controls in Image Settings. The same controls are keyboard accessible and remain visible on coarse-pointer devices.

GPT Image 2 reference editing through an OpenAI-compatible provider uses the model's built-in high-fidelity input handling; ChatHub omits the unsupported input_fidelity request option so reference edits are not rejected for that field. When a compatible Images API returns base64 output as PNG, JPEG, or WebP, ChatHub labels the result with the matching format before storing or displaying it.

When a stored image appears in a chat after messages are refreshed, ChatHub tries to replace each authenticated /webapi/files/... URL with a provider- accessible object URL. This lookup is best-effort per image: one stale or deleted reference does not stop the send, but the provider may still be unable to fetch the unchanged proxy URL. Generated image output follows a stricter path and succeeds only after ChatHub can fetch or decode, transform, and store the provider result.

OpenAI-compatible image usage keeps all reported totals and explicit zeroes. If the provider reports image-input tokens but omits text-input tokens, ChatHub derives text input as total input minus image input (never below zero) to avoid double charging. If the modality breakdown is unavailable, ChatHub leaves it unknown instead of inventing one; missing optional usage details do not fail a completed image.

GPT Image 2 sizes

The OpenAI-compatible GPT Image 2 model has a dedicated Size control. This does not change the size options shown by native OpenAI models or other image providers.

• Auto: lets the provider choose the size.
• Standard: 1024x1024, 1536x1024, and 1024x1536.
• 2K / QHD: 2560x1440 landscape and 1440x2560 portrait.
• 4K / UHD: 3840x2160 landscape and 2160x3840 portrait.
• Custom: accepts another valid width and height.

To use a Custom size, select Custom, enter the width and height, and select Confirm. ChatHub does not change the active Size until both values are valid. Select Cancel or press Escape to keep the previous selection.

Custom dimensions must meet every rule below:

• width and height are multiples of 16 pixels
• neither edge is greater than 3840 pixels
• the longest edge is no more than three times the shortest edge
• the image contains between 655,360 and 8,294,400 total pixels, inclusive

Sizes above 3,686,400 total pixels show an experimental warning. The 2K presets are exactly at the reliable boundary and do not show the warning; both 4K presets do. Experimental sizes are still selectable, but a compatible gateway may impose additional limits or take longer to process them.

Valid Custom sizes are remembered in the same way as preset Size choices: signed-in users sync them with their account, and guests keep them in the current browser. If a remembered Custom size becomes invalid after a model configuration change, ChatHub returns GPT Image 2 to Auto. Generation and reference editing send the exact confirmed WIDTHxHEIGHT value to the compatible Images API.

Retry behavior

When one or more images in a batch fail, use Regenerate to retry only those failed outputs immediately with the original provider, model, prompt, reference images, and runtime settings. Successful images stay in the original batch. The action does not appear when every image succeeded. ChatHub refreshes access to stored reference images when the retry is submitted, so a batch can be regenerated after the Image page has remained open for a long time.

Regenerate appears before Reuse Settings:

• Use Regenerate for an immediate failed-only retry.
• Use Reuse Settings when you want to load the original settings, edit them, and submit a new generation yourself. It remains available on successful and failed batches.

Only the batch being retried shows a disabled progress indicator, and repeated clicks for that batch are ignored. ChatHub submits the replacement before removing failed results. If every result failed, it removes the old batch after the replacement is accepted. For mixed results, it removes only the failed records and preserves successful siblings.

If replacement submission fails, all original results remain available and ChatHub shows the generation-start error. If submission succeeds but old failed results cannot be fully cleaned up, the replacement remains accepted and ChatHub asks you to refresh the topic to reconcile any duplicate failed records. Retry reconciliation remains attached to the Image Topic where Regenerate was selected, even if you switch to another topic before the retry finishes. Switching accounts cancels an active retry and prevents it from changing the new account's image history.

Very old batches can contain an ambiguous stored reference-image path that cannot be distinguished safely from a legitimate object-storage key. ChatHub leaves those results unchanged instead of retrying with a potentially different image. The failed Regenerate notification shows the recovery workflow: use Reuse Settings, remove and add the reference image again, then submit a new generation.

If a batch reports an invalid provider API key, correct the credentials and select Confirm. That recovery screen uses the same regeneration operation; because the batch contains only failures, ChatHub replaces the whole failed batch after the new submission is accepted.

Troubleshooting

Symptom	Action
Image is missing from navigation	Confirm the deployment is running in server mode and the ai_image feature is enabled.
Generate is disabled	Enter a prompt containing at least one non-whitespace character and confirm an image provider/model is enabled.
Image Settings shows "Unable to load Image Settings"	Check the network connection and select Retry. On mobile, leave the bottom drawer open while retry runs. If Sign in again appears, ChatHub detected an account mismatch, cleared loaded account data and credentials, blocked account refreshes and settings changes, and cancelled work owned by the invalid session; use that command instead of retrying.
Number of Images covers another setting while scrolling	Update to a current ChatHub image. The control should be the final normal-flow item and scroll with the complete settings form.
Generation could not start	Reopen Image Settings and verify the provider, model, credentials, and supported parameters.
GPT Image 2 Custom size cannot be confirmed	Check that both edges are multiples of 16, no edge exceeds 3840, the aspect ratio is at most 3:1, and the total pixel count is within the displayed limits.
GPT Image 2 shows an experimental warning	The selected size exceeds 3,686,400 total pixels. Choose a Standard or 2K preset for the reliable range, or continue only if the compatible provider accepts the larger request.
A saved GPT Image 2 Custom size returned to Auto	The saved value no longer satisfies the active model contract. Re-enter a valid Custom size or choose a preset.
Invalid API key	Update that provider's API key, then select Confirm to regenerate the failed batch.
Some images in a batch failed	Select Regenerate to retry only failed outputs and preserve successful images. Use Reuse Settings instead when you want to edit the original configuration first.
Regenerate says a stored reference format is ambiguous	The batch predates reference-format tracking. Use Reuse Settings, remove and add the reference image again, then submit a new generation. ChatHub leaves the original results unchanged.
Regenerate reports that cleanup failed	The replacement was accepted, but some old failed records may remain. Refresh the Image Topic to reconcile the batch; successful originals are preserved.
Reference image cannot upload	Verify the file type/size and object-storage configuration, then retry.
A new mobile Image Topic stays untitled or generation continues only in the background	Upgrade to a current ChatHub image and reopen Image once. Current versions register the permanent topic before title generation and keep its queued tiles active without opening Image Topics.
An Image Topic title displays with surrounding ** markers	Upgrade to a current ChatHub image. New titles are normalized before saving, and historical Markdown-wrapped titles are displayed as plain text.
Image succeeds after an intermittent input_tokens_details error	Upgrade to a current ChatHub image. Some OpenAI-compatible providers intermittently omit optional usage breakdowns; current versions preserve the generated image and available totals instead of failing telemetry conversion.
Maximum call stack size exceeded after the provider completed	Upgrade to a current ChatHub image. Older versions could fail while parsing a large inline base64 result after the provider had generated it successfully; changing provider settings does not address this local post-processing error.
Prompt cards in chat, pictures only in Artifacts	Upgrade to a current ChatHub image. Current versions keep the file id on the chat tile when a later message refresh is stale and attach the saved Artifacts file for that prompt. If Retry is still running, leave the topic open in this tab until the picture appears. A topic with several prompts does not assign Artifacts pictures by gallery or list order. If a card is still only Prompt text after that image, press Retry.
Unexpected token '<' or HTML response in server logs	Enable CHATHUB_IMAGE_DEBUG=1, recreate the container, submit one image, and check for chathub-image-debug dispatch/response events.

For production-safe server diagnostics, use CHATHUB_IMAGE_DEBUG=1 as described in Debug and Diagnostics for the Image workspace. Chat Image tool tiles in a conversation use CHATHUB_GENERATION_DEBUG=1 (chat_image_* events) instead. Response diagnostics sample the normal internal JSON read without cloning the response stream, and internal correlation headers are accepted only with the server bearer credential. Provider identifiers appear only as keyed hashes, and each async request has one terminal async_route_settled outcome. Avoid DEBUG=lobe-image:* in privacy-sensitive environments because legacy namespaces can expose prompts or URLs.

The in-chat Image tool

Assistants can also generate images inline in a conversation through the built-in Image tool — enable Image in the assistant's tool picker. The model can create up to four images per request from text prompts.

The chat tool reuses your Image workspace configuration: it generates with the same provider, model, and size/quality options you last selected in Image Settings, so changing your image model there also changes what the chat tool uses. It never sends a reference image, so the chat tool always performs a fresh text-to-image generation.

• Generation runs in the background the same way the Image workspace does: the chat polls for the finished image instead of holding a request open, so slow models (for example 4K GPT Image 2 renders that take 30–60 seconds) work reliably even behind proxies or CDNs, and the finished image is stored durably on the server before it appears in the chat.
• Each image remembers its background task, and the task id is saved with the message before the generation request is even sent — so navigating away, reloading, or closing the tab mid-generation cannot orphan a task that was already submitted. Opening that conversation again picks a running or finished task back up: a finished image is filled in and a still-running one resumes waiting. If Stop happened after the task id was saved but before the paid create ran, remount and reload do not start that generation automatically — the tile shows that it was stopped and waits for Retry. ChatHub records the stopped task in this browser immediately, then writes a cancelled placeholder for that unpaid id on the server as soon as you press Stop — it does not wait for the rest of the conversation to finish cancelling — so another device opening the same conversation also will not auto-start, including when the conversation save is interrupted. Already- stopped image tiles are not sent again, so a long image-heavy topic still records the unpaid ones. If the server never receives that Stop (the tab is offline) and this browser cannot store the stop id (storage blocked or full), a later reopen can still treat the unpaid id as crash recovery; press Retry only if you still want that image. A later image that you started after Stop, then lost to a tab crash before the provider request, still resumes on reload. Retry reuses an existing successful or still-running task; a new (paid) generation is only started when you press Retry after Stop, or when the server itself reports the previous task failed. If Image tiles already show a generic server error (PRECONDITION_FAILED) from an earlier build, press Retry — that resubmits the same unpaid id and does not double-bill a task that never started. One deliberate exception: conversations brought in from a backup or import do not restart image generations on their own — such an image shows a short "could not be verified" note and waits for you to press Retry, so restoring old chats can never silently start new paid generations.
• If no image model is enabled, the tool shows a clear "no image model" message instead of generating.
• If one image fails, its card shows the error with a Retry button that regenerates only the failed image — successful images are kept and not re-generated.

If Prompt cards appear and you switch topics, generation should keep going in that tab — leaving a topic is not Stop. Open or return to the topic once so a Prompt-only card can attach a finished file or join a still-running Retry; after that, switching topics does not stop the in-tab poll. Keep the browser tab open if you want the card to attach as soon as the file is ready. Closing the tab stops that wait, not the submitted server task: generation still finishes and is stored in Artifacts, and reopening the topic adopts the durable file. If the topic still shows only the Prompt text after the files appear in Artifacts, upgrade to a current ChatHub image — each chat card should pick up its finished file without generating again, including after you reopen the topic. Several prompts in one tool call are not matched by Artifacts list order. If a card is still Prompt-only on that image, press Retry. If iPhone/Safari shows Load failed during Deep Thinking before any cards appear, send again — that is a WebKit abort, not a stuck tile. Operators diagnosing either case should enable CHATHUB_GENERATION_DEBUG=1 (see Debug and Diagnostics), not CHATHUB_IMAGE_DEBUG.