Image generation

ToolsAPI provides asynchronous OpenAI-backed image generation for the web interface, authenticated API clients, approved integrations and, when enabled, a restricted guest page.

The same job and status model is used across these entry points. A client can keep polling the returned status URL or request a completion notification and leave the generation running in the background.

Web image generator

Authenticated users with image-generation access can use /admin/openai/images.

The page supports prompt generation, multiple numbered reference images, custom output sizing, optional reference downscaling, removal of selected reference images, live queued progress, structured safety-rejection details, automatic reject retry and completion notifications.

Reference images are addressed as {1}, {2}, {3} and so on. Removing a selected file recalculates the remaining reference numbers before submission.

Safety rejects and automatic retry

Provider safety rejects are terminal image-generation results rather than generic queue crashes. When available, Tools exposes structured fields such as:

failure_type
error_code
error_type
request_id
moderation_stage
moderation_categories
rejection

If automatic retry is enabled, Tools performs one prompt-adjustment request using the original prompt and the structured rejection details. Harmless intent, composition and reference placeholders are preserved where possible. The adjusted prompt is then sent to the image generator once.

The retry path is limited to one adjusted image attempt to avoid loops.

The web progress flow is:

Queued -> Prepare -> Generate -> Retry -> Prepare -> Generate -> Store -> Done

The Retry stage is yellow while the prompt is being adjusted, green when the adjusted retry path succeeds and red when the retry ultimately fails.

Authenticated image API

Start a generation:

POST /api/ai/openai/images

Read status:

GET /api/ai/openai/images/{sessionId}

New image-specific API tokens should use the scope ai.image.generate. Compatible trusted AI and StorageAPI image-generation scopes can also be accepted according to the account policy.

Image-generation access can be granted through an accepted API token, an account permission or an eligible paid account. GUI, API, X-bot and guest entry points have independent feature policies.

Example request:

{
  "prompt": "Create a cinematic landscape using {1} as the reference.",
  "model": "gpt-image-1",
  "size": "1536x1024",
  "quality": "high",
  "retry_on_reject": true,
  "notify_methods": ["callback"],
  "callback_id": 12
}

The API has its own default for retry_on_reject; it does not inherit the web-page default. An explicit value overrides the feature default only when request-level override is enabled for that feature.

A successful start returns HTTP 202 with a job/session ID and status_url. The original HTTP connection does not need to stay open while generation runs.

Completion notifications

A generation can request one or more allowed methods:

email
sms
callback

Example:

{
  "notify_methods": ["email", "sms"]
}

The boolean convenience fields notify_email, notify_sms and notify_callback are also accepted.

Email uses the address stored on the authenticated account. SMS uses the mobile number stored on the account. Callback delivery requires a previously registered callback ID.

Notifications can be sent after completion, rejection or failure.

Registered callbacks

Callbacks are registered before they can be attached to an image job. A generation request cannot submit an arbitrary callback URL directly.

List registrations:

GET /api/ai/openai/image-callbacks

POST /api/ai/openai/image-callbacks

{
  "name": "My image receiver",
  "url": "https://example.com/tools/image-callback",
  "events": [
    "image_generation.completed",
    "image_generation.rejected",
    "image_generation.failed"
  ]
}

The create response includes a signing_secret. The secret is shown only when the callback is created or explicitly rotated.

Update:

PATCH /api/ai/openai/image-callbacks/{callbackId}

Delete:

DELETE /api/ai/openai/image-callbacks/{callbackId}

Rotate signing secret:

POST /api/ai/openai/image-callbacks/{callbackId}/rotate-secret

Dry run

A callback can be tested without generating an image:

POST /api/ai/openai/image-callbacks/{callbackId}/dry-run

The dry run uses the same URL checks, signing and delivery format as a real callback and identifies itself with event image_generation.callback_test and dry_run: true.

Delivery status is recorded so a callback can be validated before live image jobs use it.

Callback signature verification

Callbacks are JSON requests containing:

X-Tools-Event
X-Tools-Timestamp
X-Tools-Signature
X-Tools-Delivery

X-Tools-Signature has the form sha256=<hex digest>.

To verify it, calculate HMAC-SHA256 over:

<TIMESTAMP>.<RAW_JSON_BODY>

Use the callback's signing secret and compare the generated digest with a timing-safe comparison. Receivers should also enforce their own replay-window policy for timestamps.

Callback events

A callback can subscribe to:

image_generation.completed
image_generation.rejected
image_generation.failed

Completed payloads can contain the generated image result. Rejected payloads can contain structured moderation details. Retry metadata can include whether retry was attempted, its final state and the adjusted prompt used for the second image attempt.

Usage accounting

Provider consumption is attributed to the authenticated user or configured service account.

A reject-retry sequence consumes separate operations:

Initial image-generation attempt.
Prompt-adjustment model request.
Second image-generation attempt when adjustment succeeds.

The existing image usage accounting records each image-provider attempt, and prompt-adjustment usage is also recorded.

X-bot image generation

X-bot uses the same image job, policy and reject-handling core:

POST /api/x-bot/images

Status:

GET /api/x-bot/images/{sessionId}

X-bot keeps its additional Social Media Tools authorization checks.

Optional guest generator

When enabled, a restricted public generator is available at /image-generator.

Guest generation is disabled by default and has its own limits for request frequency, prompt length, reference images, models, sizes, quality and reject retry. Guest status URLs include a separate unguessable status token so knowing a job UUID alone is insufficient to read another guest job.

The guest interface intentionally exposes a smaller feature set than authenticated image generation.

Operational Slack reporting

Operators can enable image-generation lifecycle reporting through the Tools Slack integration. Reports can include retry start, adjusted-prompt acceptance, completion, rejection and failure information.

Prompt text is excluded from Slack reports by default and is only included when explicitly enabled by the operator.

Errors

Clients should distinguish between request/authentication errors when starting a job, queued jobs that later fail and safety rejects where failure_type is rejected. Preserve provider request IDs when diagnosing upstream rejections.

Tornevall Networks