Image Generation & Gallery

The Image Gallery is the central store for all AI-generated images of a team. Every image created in chat or in the article editor lands permanently under /images — with filters, tags, favorites, soft delete, and 30-day trash. The edit modal can produce variants (image-to-image via OpenAI gpt-image-2) that hang as children on the original. Public share links make individual images shareable without login.

What it can do

• Generate — POST /v1/generate/image creates a new image for a prompt. Async, the result appears in the gallery.
• Gallery & trash — GET /v1/images with filters (q, model, from, to, favorite, tags[], sort, page). GET /v1/images/trash lists soft-deleted, 30-day retention, then automatic hard-delete.
• Edit (soft edit) — POST /v1/images/{id}/edit starts a variant async. Response 202 with {job_id, edit_session_id}, frontend polls /v1/images/{id} and sees the new variant in variants[].
• Metadata — PATCH /v1/images/{id} for title and tags[], POST /v1/images/{id}/favorite toggles the star.
• Bulk operations — bulk delete/restore (max 200), bulk export as ZIP (max 500, async via /v1/images/exports/{job_id}).
• Public share — idempotent 40-char token, public URL without login with noindex,nofollow, optional expiry, and view counter. Audit trail is preserved after revoke.
• Open in chat — POST /v1/images/{id}/open-in-chat creates an AiChatSession with gallery_image_id; the agent can keep working with the image as a source.

When to use

• You need hero images, OG images, or inline visuals for your articles and want to archive them reusably.
• You want to nudge an existing AI visualization (color, detail, style) instead of regenerating from scratch.
• You want to share an image without a platform login with clients / editors.
• You want to bulk-export images — e.g. for a WordPress sync or an external DAM.

Workflow

1. Generate — POST /v1/generate/image with {prompt, model?}. The image lands in the gallery.
2. Browse & filter — GET /v1/images?tags[]=hero&sort=newest lists matching images.
3. Edit — POST /v1/images/{id}/edit with prompt → variant hangs on the parent. Frontend polls /v1/images/{id} until variants[] is populated.
4. Clean up — DELETE /v1/images/{id} moves to trash (30-day restore window). DELETE /v1/images/{id}/forever (only from trash) deletes permanently.
5. Share or process further — POST /v1/images/{id}/share creates a public link, POST /v1/images/{id}/open-in-chat opens a chat session with the image as context.

API

Credits & Limits

• Generate: 5 credits.
• Edit: 10 credits (same tariff as Generate; OpenAI backend cost is higher on the edit endpoint).
• Bulk caps: delete/restore max 200 IDs, export max 500 IDs per request.
• Trash auto-prune: 30 days, then hard-delete via cron.
• PNG required for edits: JPEG/WEBP are converted server-side to PNG ≤4MB.
• Team scoped: cross-team → 404.

Related modules

• AI Content Editor — images from the gallery can be inserted directly into articles.
• Agentic Chat — generated images appear immediately in the gallery; Open in Chat opens a new edit session.
• Rankion OS — images can be referenced and shared in OS folders.