Image is one managed image; Gallery is an ordered collection. Upload a file and the server processes it into configured sizes. Saving the record attaches the image. This differs from a string containing an arbitrary URL.
Adding a field
In Content → Add field, select Image or Gallery, enter a name and profile, such as cover or avatar. Check sizes, quality and whether the value may be empty. Finish and Generate.
| Parameter | Default | Allowed settings |
|---|---|---|
profile |
photo |
photo, avatar, cover, custom. |
formats |
jpeg,png,webp |
One or more of these input formats without duplicates. |
maxCount |
10 | 1–10 gallery images. |
maxBytes |
10485760 | 1–10485760 bytes per file. |
maxPixels |
25000000 | 1–25000000 pixels. |
quality |
85 | 1–100. |
output |
auto |
auto, jpeg, png. |
aspect |
Original proportions; avatar: 1; cover: 16/9 |
0 preserves proportions; otherwise 0.01–100. |
sizes |
sm: 320, md: 768, lg: 1600 |
1–4 variants with width 1–4096. Default avatar: 64/128/256. |
sizes names must be unique lowercase identifiers. master is reserved for the base image.
image and gallery do not support primary keys, uniqueness, indexes, general search/sort/filter, default, automatic generation, Hidden, Readonly or regular scalar constraints. An optional image can store null.
Upload processing
Select a file in the record form, or ordered files for Gallery. Retry or remove failed uploads. Prepared images attach when the record is saved; uploading alone does not change the saved article.
Crop, replacement and Update sizes create a new version. An existing published record remains unchanged until save. A new output format applies during the next processing operation.
After orientation normalization, the original uploaded file is deleted. A PNG master remains for recropping; metadata is removed. Processing does not guarantee print-workflow accuracy or wide-gamut ICC support.
File storage
For local storage, MEDIA_ROOT is an absolute persistent directory outside source files. Default: ~/.local/share/<project>/media. Different databases need different directories. See storage for S3.
Generate preserves actual images and custom code. However, some model changes, such as renaming/removing media fields, switching image/gallery or stricter requirements, may be blocked before generation.
Adding media to an existing project may require manually updating dependencies. The generator does not rewrite your go.mod or install packages.
External-client response
Persistent and virtual external APIs return ready URLs:
{"image":{"assetId":"...","alt":"Интерфейс проекта","size":{"sm":"/api/external/v1/_media/.../files/sm","md":"/api/external/v1/_media/.../files/md","lg":"/api/external/v1/_media/.../files/lg"}}}
size keys match field variants. Clients need no separate metadata request. Gallery returns these details for every item. Only prepared variants of attached images are published; master is not exposed. Admin upload/selection remains a separate contract.
The URL opens the file. Later hiding a record through external rules does not revoke its earlier URL. Current Cache-Control permits five minutes of caching. This delivery mechanism does not promise confidential-file access control.
Custom controls or SQL
Connect a control through imageFields, which uses typed references. If custom SQL bypasses generated repositories, maintain the attachment registry yourself. Otherwise, cleanup cannot correctly match files to records.
Optional: CLI configuration
Pass field settings as JSON:
admingen-cli --path ./docs-demo field add Article cover --type image --nullable \
--image-settings '{"profile":"cover","quality":85,"output":"auto"}'
Cleaning unattached files
Cleanup is a separate maintenance operation. The editor has no background-cleanup button. From backend, using the application's environment, run:
go run ./cmd/media-cleanup --limit 100
--limit accepts 1–100. Expired unattached data is removed. No automatic schedule is created. Coordinate stopping both writes and cleanup when taking a snapshot or restoring.
Form settings: Content: images; storage: operating storage; cleanup: application commands.