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: