Upload or attach a user-supplied or externally-designed image (bring-your-own asset) to a post: the creator's own visual (a product shot, their actual work, a card designed elsewhere) instead of an AI-generated image (niche_render_image_card photo, paid) or a flat brand card. Free, with no image-generation spend. For a visual-product maker the real piece is the sale.
Input modes, in order of preference: (1) `upload_ref`, the FAST path for an agent that built the asset itself and can run a shell: POST the raw file to `/asset/upload` (multipart/form-data, your bearer token) to get back an `upload_ref`, then pass it here. The bytes travel over HTTP and never round-trip through the model as base64, so it's effectively instant for a real graphic. (2) `image_url`, a fetchable https URL (the server fetches + stores it; for an asset that already lives on the web). (3) `image: {mime_type, data_base64}`, inline base64, fine for small images only. (4) `image_chunk`, the no-shell FALLBACK: upload bounded chunks of base64. It still re-types the bytes through the model (slow), so use it only when the agent has no shell to curl with. Split the file's bytes into ~32-48KB pieces, base64 EACH independently, send in order, each with a `sha256` of that piece's raw bytes so the server catches a mis-transcribed chunk and has you resend just that one (this is what makes the slow path reliable). Omit upload_id on the first chunk; the response returns one to pass on the rest. Set `final:true` on the last chunk (optionally with `total_sha256`); that call assembles, validates, and attaches.
The cell's output must already exist (use niche_add_output first if needed). Sets it as the post's image; publishes with the caption. A dimension_note warns if the image's aspect won't fit the cell. Undo-able (the prior image is kept in history).