hive-image-generation

# Image generation `image_generate` turns a text prompt into an image (and can edit existing images). It routes through the Hive image service to OpenAI's **gpt-image-2**; the cost is billed to the user's Hive credits exactly like an LLM call, so there is **no API key to configure**. Each generated image is also saved to disk. ## The call ``` image_generate( prompt: str, # required — what to draw reference_images: list[str] = None,# local paths or http(s) URLs to edit/condition on size: str = "1024x1024", # 1024x1024 | 1536x1024 (landscape) | 1024x1536 (portrait) | auto quality: str = "low", # low only (medium & high disabled) n: int = 1, # 1–4; each image is billed separately output_format: str = "png", # png | jpeg | webp model: str = "gpt-image-2", ) ``` Defaults are deliberately cheap and fast. **`quality` is locked to `low`** — `medium` and `high` are disabled for cost control, and any request for a higher tier is automatically forced to `low`. Only raise `n` when the user explicitly wants variations. ### Writing the prompt Be concrete: name the subject, style (photo, flat vector, 3D, watercolor…), composition/framing, color palette, mood, and any **text to render** (gpt-image-2 renders text well — quote it exactly, e.g. `the words "Launch Day" in bold`). ## Reference-image editing Pass `reference_images` to edit, restyle, or compose from existing images — restyle a product photo, place a logo on a mockup, keep a character's identity across images, or merge elements. Provide up to 10 local file paths or `http(s)` URLs; the model conditions on them at high fidelity. Example: ``` image_generate(prompt="Put this product on a marble kitchen counter, soft morning light", reference_images=["data/uploads/bottle.png"]) ``` A good source of reference images is something the user attached (read it from the path in their message) or an image you generated earlier (use its saved `path`). ## How it runs — start, then collect (it's asynchronous) Image generation can take a couple of minutes, so `image_generate` **runs in the background**: it returns immediately with `{"status":"started","handle":"bg_…"}`. You then poll the generic **`collect_result`** tool with that handle until the image is ready: ``` start = image_generate(prompt="A minimalist bee logo, flat vector, amber on white") # start.handle == "bg_1" res = collect_result(handle="bg_1", wait_seconds=30) # → {"status":"pending", ...} ← not done yet; call collect_result again # → eventually the real result: {"images":[{"path": …}], "usage": …, …} ``` `collect_result` waits up to `wait_seconds` (≤45) per call and returns `{"status":"pending"}` until generation finishes — just call it again with the same handle until you get the real result. It's fine to do other small things between polls. Don't start a second image while one is pending unless the user asked for several. ## Show the user The finished result's JSON has `images` (each with a `path`) plus `model`, `n`, and `usage`; one image is previewed inline. **Call `attach_file(path)` on the image path** to surface a downloadable chip in chat. Do not paste base64 or write `` markdown. ## Failure modes Errors surface in the `collect_result` result as `{"error": ...}` (the tool never raises). Handle these: - **Out of credits / subscription inactive** (`status: 402`) — tell the user they're out of Hive credits; do **not** retry. - **Model unavailable / org verification** (`status: 403`) — report that image generation is currently unavailable; do not loop. - **Request rejected / moderated** (`status: 400`) — the prompt was likely refused; rephrase it (less explicit, no real-person likeness) and try once. - **Rate limited** (`status: 429`) — wait a moment and retry once. - **Still `pending` after several minutes** — collect_result keeps returning pending well past ~4 min: the job likely failed. Tell the user and start once more. (`{"error":"Unknown … handle"}` means it was already collected or never started — just start a fresh image_generate.) ## End-to-end example User: "make us a logo — a friendly robot, simple and modern." 1. `image_generate(prompt="A friendly modern robot mascot logo, simple flat vector, rounded shapes, teal and white, centered, plain background", quality="low")` → `{"status":"started","handle":"bg_1"}` 2. `collect_result(handle="bg_1", wait_seconds=30)` — repeat until it returns the real result (not `{"status":"pending"}`). 3. Take `result.images[0].path`, call `attach_file(that_path)`. 4. Reply briefly: "Here's a first take — want it bolder, a different color, or any tweaks?"