Images & assets

Images and other binaries are committed to the same GitHub repo that hosts the document and referenced with a relative path (![alt](../assets/x.webp)), so they render on GitHub, Obsidian, Foam and any Markdown viewer — with no expiring URLs.

Why not paste base64?

A naïve “upload” tool makes the model emit the file as base64, token by token — slow, expensive, and easy to corrupt. Blenau avoids this entirely: the bytes travel straight to Blenau over HTTP and never pass through the language model.

The optimal flow (agents)

1. Call create_asset_upload(doc_path, filename). It returns a short-lived upload_url (and the size limit + compression guidance) — not a request for the file content.

2. Transfer the local file with one shell command:

   curl -F file=@./diagram.webp "<upload_url>"

3. The response carries the ready-to-paste markdown and the commit_sha.

To embed the image into the document in the same step, add form fields. An image earns its place by reinforcing the text right where the reader needs it — which is almost always right after the sentence or step it illustrates, not parked at the top of a section. So the preferred anchor is insert_after_text:

curl -F file=@./diagram.webp \
     -F alt_text="Webhook URL field, pre-filled" \
     -F insert_heading="Setup" \
     -F insert_after_text="Open the integration settings panel." \
     "<upload_url>"

Use insert_heading + insert_position when a section-level anchor is good enough:

curl -F file=@./diagram.webp \
     -F alt_text="Settings screen" \
     -F insert_heading="Setup" \
     -F insert_position=after \
     "<upload_url>"

insert_position is one of after · before · append · prepend. With an insert_heading the image is anchored to that section: after/prepend place it at the top of the section, append at the bottom, before just above the heading. Without a heading, prepend/append target the whole document. To drop the image right after a specific paragraph, add -F insert_after_text="<verbatim snippet>" alongside the heading.

If the heading is missing or duplicated (or the insert_after_text snippet isn’t found), the embed fails loudly (insert.embedded=false with a reason and the list of available_headings) — the image is never silently dumped at the top of the document. On success the insert block reports verified and placed_under_heading. Blenau splices the image cleanly and re-commits the doc, so GitHub stays the source of truth and the document layout stays tidy.

Omit all insert_* fields for an upload-only call: the response still carries asset_path and markdown, and the document is left untouched.

The optimal flow (CLI)

The CLI holds your token, so it uploads directly:

blenau assets upload ./diagram.webp \
  --doc "emboux/setup/odoo-sync.md" \
  --alt "Settings screen" \
  --insert-at "## Setup" --position after

Add --compress to auto-optimize an oversized image before upload (uses magick or cwebp if present).

Size limit & compression

Assets live in git history forever, so they must stay small. The limit is 1 MB. If your image is larger, optimize it locally before uploading — never read the file into the model’s context, just run a shell tool:

# ImageMagick (any input):
magick input.png -resize '1600x1600>' -quality 80 output.webp

# cwebp (lightweight, WebP only):
cwebp -q 80 -resize 1600 0 input.png -o output.webp

# pngquant (keep PNG):
pngquant --quality=60-80 input.png

Install ImageMagick: macOS brew install imagemagick · Windows winget install ImageMagick.ImageMagick · Debian/Ubuntu apt install imagemagick. A well-optimized WebP at 1600px wide is typically 50–200 KB — comfortably under the limit.

Good to know

• Content-addressed names. Stored assets are named assets/<sha8>-<name>, so two different images called screenshot.png never collide, and re-uploading the same bytes deduplicates automatically.
• Legacy base64 path. A base64 upload_asset tool still exists but is capped at 64 KB — use it only for tiny inline icons (e.g. a small SVG). For everything else, use create_asset_upload / blenau assets upload.