{"result":{"depiction_url":null,"edges":{"in_module":{"objects":[{"created":"2026-09-09T13:48:11Z","object_id":{"id":335,"is_a":["text","documentation","reference","module"],"name":"doc_core","title":"Zotonic Core","uri":"https:\/\/zotonic.com\/id\/335"},"seq":1}],"predicate":{"id":333,"is_a":["meta","predicate"],"name":"in_module","title":{"_type":"trans","tr":{"en":"In module"}},"uri":"https:\/\/zotonic.com\/id\/in_module"}},"subject":{"objects":[{"created":"2026-09-09T13:48:11Z","object_id":{"id":2555,"is_a":["categorization","keyword","keyword_information_type"],"name":"zotonic_topic_reference","title":"Reference","uri":"https:\/\/zotonic.com\/id\/2555"},"seq":1},{"created":"2026-09-09T13:48:11Z","object_id":{"id":2564,"is_a":["categorization","keyword","keyword_audience"],"name":"zotonic_topic_backend_developer","title":"Backend developer","uri":"https:\/\/zotonic.com\/id\/2564"},"seq":2},{"created":"2026-09-09T13:48:11Z","object_id":{"id":2576,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_media_management","title":"Media management","uri":"https:\/\/zotonic.com\/id\/2576"},"seq":3},{"created":"2026-11-05T18:43:02Z","object_id":{"id":2581,"is_a":["categorization","keyword","keyword_domain"],"name":"zotonic_topic_file_storage","title":"File storage","uri":"https:\/\/zotonic.com\/id\/2581"},"seq":4},{"created":"2026-09-09T13:48:11Z","object_id":{"id":2619,"is_a":["categorization","keyword","keyword_architecture"],"name":"zotonic_topic_media_resource","title":"Media resource","uri":"https:\/\/zotonic.com\/id\/2619"},"seq":5},{"created":"2026-09-09T13:48:11Z","object_id":{"id":2625,"is_a":["categorization","keyword","keyword_architecture"],"name":"zotonic_topic_model","title":"Model","uri":"https:\/\/zotonic.com\/id\/2625"},"seq":6},{"created":"2026-09-09T13:48:11Z","object_id":{"id":2643,"is_a":["categorization","keyword","keyword_task"],"name":"zotonic_topic_query","title":"Query","uri":"https:\/\/zotonic.com\/id\/2643"},"seq":7}],"predicate":{"id":308,"is_a":["meta","predicate"],"name":"subject","title":{"_type":"trans","tr":{"en":"Keyword"}},"uri":"http:\/\/purl.org\/dc\/elements\/1.1\/subject"}}},"export_revision":4161,"id":1284,"is_a":["text","documentation","reference","model"],"links":[{"rel":"self","target":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/1284"},{"rel":"hub","target":"https:\/\/zotonic.com\/.zotonic\/websub"}],"medium":null,"medium_url":null,"name":"doc_model_model_media","page_url":{"en":"https:\/\/zotonic.com\/docs\/1284\/media","x-default":"https:\/\/zotonic.com\/docs\/1284\/media"},"preview_url":null,"resource":{"version":4161,"pivot_location_lat":null,"title":"media","is_authoritative":true,"body":"

Access to data about uploaded files and other media.<\/p>\n

The medium<\/code> (singular form of media) table stores all information of uploaded files or other media. Every resource can\ncontain a single medium. A resource with a medium is most often of the category image, audio, video or document.<\/p>\n

In template the m_media<\/code> model is used to fetch the medium record by the resource id: m.media[id]<\/code>. This is the same\nfunction as with m.rsc[id].medium<\/code> except, that the m_rsc model does access control checks and the m_media does not.<\/p>\n

The m_media<\/code> model implements all functions to handle media files and is used by other Erlang modules.<\/p>\n

Owned uploaded files and explicit previews use m_cafs<\/code> for content-addressable\nstorage. filename<\/code> and preview_filename<\/code> remain logical filenames used by image\nand media URLs; they need not exist as individual files in the archive directory.\nResolve files through Zotonic's file APIs instead of constructing local paths.\nIdentical bytes can share storage without sharing resource permissions.<\/p>\n

The optional digest<\/code> property is the lowercase hexadecimal SHA-256 digest of the\noriginal bytes. Legacy media can lack a digest or CAFS mapping; existing files are\npromoted on demand when their bytes are available. Reading a medium does not fetch\nremote bytes to calculate a digest. See model#m_cafs<\/code><\/a> for the storage lifecycle,\npreview retention, and internal Erlang APIs.<\/p>\n

Copy a medium to another resource<\/h2>\n

m_media:migrate_to_cafs(Context)<\/code> queues a resumable scan of all current medium\nrecords. It requires use mod_admin_config<\/code>. Owned originals and extracted preview\nimages are deduplicated into CAFS; logical filenames remain unchanged. Local bytes\nare hashed, while remote-only originals with a valid SHA-256 digest reuse their\nexisting remote location. Remote-only files without a digest are logged and skipped,\nnever downloaded for hashing. Retry tasks handle unavailable backends separately\nfrom the scan. Legacy remote copies are retired only after a healthy canonical\nremote copy exists; deletion follows filestore retention. Rerunning is safe.<\/p>\n

m_media:delete_generated_previews(Context)<\/code> queues background deletion of resized\nvariants and requires use<\/code> permission on mod_admin_config<\/code>. Original files and\npreview_filename<\/code> images are preserved, including CAFS bytes shared with them.\nThe maintenance page exposes this operation. Remote deletion follows filestore\nretention; requests may regenerate previews during or after cleanup.<\/p>\n

Use m_media:copy(Source, Destination, Context)<\/code> to replace an existing resource's\nmedium with a copy of another resource's medium. Both arguments accept resource\nids or names. The result is ok<\/code> or {error, Reason}<\/code>.<\/p>\n

m_media:copy(SourceId, DestinationId, Context).\n<\/code><\/pre>\n
The caller must be allowed to view the source, edit the destination, and insert\nmedia of the source's MIME type and size. Permission failures return\n{error, eacces}<\/code>; missing resources or a source without a medium return\n{error, enoent}<\/code>. Copying a resource onto itself is a no-op after these checks.\nA missing source medium never clears the destination.<\/p>\n
The source is preserved. Destination resource properties, including category,\ntitle, and image-edit settings, are unchanged. Medium properties are copied with\nthe destination id and a new creation timestamp. Owned originals and explicit\npreviews receive independent logical filenames sharing CAFS bytes; mapped remote\nobjects need no download. Legacy owned files are promoted on demand. Non-owned\nfiles, including library assets, are snapshotted into CAFS under new owned filenames\nwithout changing the source reference. Failure to prepare either owned file leaves the\ndestination medium untouched and releases newly created aliases.<\/p>\n
Replacement uses the normal medium notifications, cache invalidation, MQTT update,\nand recovery retention for the destination's previous files. This is an Erlang API;\nno HTTP or MQTT copy endpoint is provided. duplicate\/3<\/code> remains the internal\ninsertion-only helper used when duplicating a whole resource.<\/p>\n
Properties of a medium record<\/h2>\n
A medium record has minimally the following properties, other properties can be added by modules.<\/p>\n
Property<\/th>Description<\/th>Example value<\/th><\/tr><\/thead>
id<\/td>Id of the medium record, equal to the page id.<\/td>512<\/code><\/td><\/tr>
filename<\/td>Logical filename of the uploaded file. For legacy storage, this is relative to the archive directory.<\/td><<"2009\/10\/20\/zotonic-datamodel.jpg">><\/code><\/td><\/tr>
rootname<\/td>Root name of the filename.<\/td><<"zotonic-datamodel">><\/code><\/td><\/tr>
original_filename<\/td>Filename as suggested by the user agent when uploading the file. Directory paths are removed and unsafe characters replaced with underscores. The root name is limited to 80 Unicode characters; the extension is preserved.<\/td><<"Zotonic-datamodel.jpg">><\/code><\/td><\/tr>
mime<\/td>Mime type of the medium.<\/td><<"image\/jpeg">><\/code><\/td><\/tr>
width<\/td>Width in pixels.<\/td>536<\/code><\/td><\/tr>
height<\/td>Height in pixels.<\/td>737<\/code><\/td><\/tr>
orientation<\/td>Exif oritentation of the image.<\/td>1<\/code><\/td><\/tr>
sha1<\/td>Optional sha1 checksum of uploaded file. Undefined when not present.<\/td><\/td><\/tr>
digest<\/td>Optional SHA-256 digest of the original bytes as 64 lowercase hexadecimal characters. Legacy media can lack this value.<\/td><\/td><\/tr>
size<\/td>Size in bytes of the uploaded file.<\/td>71585<\/code><\/td><\/tr>
preview_filename<\/td>Optional filename for a generated file preview.<\/td><\/td><\/tr>
preview_width<\/td>Optional. Width of the generated preview.<\/td><\/td><\/tr>
preview_height<\/td>Optional. Height of the generated preview.<\/td><\/td><\/tr>
is_deletable_file<\/td>If the file should be deleted when the medium record is deleted. A boolean.<\/td>true<\/code><\/td><\/tr>
is_deletable_preview<\/td>If the optionally generated preview file should be deleted when the medium record is deleted. A boolean.<\/td>false<\/code><\/td><\/tr>
created<\/td>Timestamp when the medium record is created.<\/td>{{2009,10,20},{13,47,27}}<\/code><\/td><\/tr><\/tbody><\/table>\n
Available Model API Paths<\/h2>\n
Method<\/th>Path pattern<\/th>Description<\/th><\/tr><\/thead>
get<\/code><\/td>\/+id\/...<\/code><\/td>Return medium record for resource +id<\/code> when the resource is visible; returns enoent<\/code> for unknown resource and eacces<\/code> when not visible.<\/td><\/tr>
post<\/code><\/td>\/upload_check<\/code><\/td>Check payload digest<\/code> (SHA-256), size<\/code>, and filename<\/code> for a visible current CAFS original. Returns needed: true<\/code> on a miss, or needed: false<\/code> plus media_upload_token<\/code>.<\/td><\/tr>
post<\/code><\/td>\/+id<\/code><\/td>Replace medium of existing resource +id<\/code> from payload url<\/code> or uploaded file<\/code> (#upload<\/code>); optional payload rsc<\/code> map updates resource props. No further lookups.<\/td><\/tr>
post<\/code><\/td>\/<\/code><\/td>Create a new resource+medium from payload url<\/code> or uploaded file<\/code> (#upload<\/code>), with optional payload rsc<\/code> properties for the new resource. No further lookups.<\/td><\/tr>
delete<\/code><\/td>\/+id<\/code><\/td>Delete medium linked to resource +id<\/code> (queues file cleanup, emits media events); requires editable resource access. No further lookups.<\/td><\/tr><\/tbody><\/table>\n
Upload clients can first call \/upload_check<\/code>. Unknown, inaccessible and unavailable\nfiles return the same miss response. A successful token is signed, user-bound,\nand valid for one hour. Pass file: {media_upload_token: Token}<\/code> to the insert or\nreplace API, or use this map as a wired form field value. Source visibility and\nits current CAFS mapping are rechecked at submission. Destination ACLs, scanning,\nsanitization and media observers still run normally. Remote-only CAFS bytes can\nbe fetched server-side for this processing. Visible legacy originals with a\nmatching checksum are lazily promoted before reuse. Originals without a known checksum and files changed by previous\nconversion require a normal upload.<\/p>\n
\/+name<\/code> marks a variable path segment. A trailing \/...<\/code> means extra path segments are accepted for further lookups.<\/p>","slug":"media","is_protected":false,"visible_for":0,"tz":"UTC","language":["en"],"doc_source_hash":"940431bb968cfe2b8e365ad66010492f82cc2b33ef31d32bb27c7138e5cdcbf6","is_featured":false,"content_group_id":{"id":2551,"is_a":["meta","content_group"],"name":"content_group_imported_docs","title":"Imported documentation","uri":"https:\/\/zotonic.com\/id\/content_group_imported_docs"},"category_id":{"id":322,"is_a":["meta","category"],"name":"model","title":"Models","uri":"https:\/\/test.zotonic.com\/id\/322"},"doc_source_path":"apps\/zotonic_core\/src\/models\/m_media.erl","publication_start":"2023-06-24T08:17:58Z","github_url":"https:\/\/github.com\/zotonic\/zotonic\/blob\/master\/apps\/zotonic_core\/src\/models\/m_media.erl","pivot_location_lng":null,"doc_source_kind":"model","name":"doc_model_model_media","is_unfindable":false,"is_published":true,"pivot_geocode":null,"created":"2020-05-30T05:47:16Z","uri":null,"doc_status":"current","is_dependent":false,"erlang_app":"zotonic_core","publication_end":"9999-06-01T00:00:00Z","modifier_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"privacy":0,"doc_source_commit":"f3c6a9a2dde17cb5b121dd3e3018d9ef4b1b3943\n","erlang_module":"m_media","creator_id":{"id":336,"is_a":["person","robot"],"name":"gitbot","title":"Git","uri":"https:\/\/zotonic.com\/id\/336"},"modified":"2026-11-09T21:39:45Z","title_slug":"media"},"uri":"https:\/\/zotonic.com\/id\/1284","uri_template":"https:\/\/zotonic.com\/id\/:id","version":4161,"websub":{"hub":"https:\/\/zotonic.com\/.zotonic\/websub","topic":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/1284"}},"status":"ok"}