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?"