Attach a user-supplied photo
niche_attach_imageUpload 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).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cell | Yes | Post cell to attach onto (e.g. 'linkedin:image_post', 'x:image_post', 'instagram:image_post'). | |
| image | No | Inline image as base64: {mime_type, data_base64} (plus optional name). Max 8MB, but large inline payloads are unreliable over MCP, so prefer upload_ref or image_url. One of upload_ref / image_url / image / image_chunk is required. | |
| image_url | No | A fetchable image URL (https). For an asset that already lives on the web: the server fetches and stores it, so you don't inline a large base64 payload. One of upload_ref / image_url / image / image_chunk is required. | |
| session_id | Yes | ||
| upload_ref | No | FAST bring-your-own path. First POST the raw file to /asset/upload (multipart/form-data field 'file', Authorization: Bearer <token>); the response returns an upload_ref. Pass it here. The bytes go over HTTP, not through the model, so it's instant for a real graphic. Preferred whenever the agent can run a shell. | |
| image_chunk | No | Chunked upload for bring-your-own bytes you hold locally (no URL). Split the file's BYTES into ~32-48KB pieces, base64-encode EACH piece, send in order. Always include a per-chunk `sha256` (hex of that piece's raw bytes): the server verifies it and rejects a mis-transcribed chunk so you resend just that one, which is what makes this path reliable (valid base64 can still decode to wrong bytes and silently corrupt the image). Omit upload_id on the first chunk (the response returns one); set final:true on the last, optionally with `total_sha256` of the whole file. |