aden-hive/hive / core/framework/skills/_default_skills/image-generation
hive.image-generation
VerifiedRequired before calling image_generate. Create and edit images from a prompt — generate an image, make a picture / logo / illustration / icon / banner / poster / thumbnail / hero image / mockup / product shot / social graphic, or edit / restyle / combine existing images from reference images. Uses OpenAI gpt-image-2 through the Hive image service, billed to the user's Hive credits like an LLM call (no API key needed). Teaches the exact call shape, the quality/cost tradeoff (quality="low" is the default and cheapest), reference-image editing, how to show the result to the user with attach_file, and the failure modes (out of credits, model unavailable, moderation).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.4 KB |
SKILL.md
View on GitHub---
name: hive.image-generation
description: Required before calling image_generate. Create and edit images from a prompt — generate an image, make a picture / logo / illustration / icon / banner / poster / thumbnail / hero image / mockup / product shot / social graphic, or edit / restyle / combine existing images from reference images. Uses OpenAI gpt-image-2 through the Hive image service, billed to the user's Hive credits like an LLM call (no API key needed). Teaches the exact call shape, the quality/cost tradeoff (quality="low" is the default and cheapest), reference-image editing, how to show the result to the user with attach_file, and the failure modes (out of credits, model unavailable, moderation).
metadata:
author: hive
type: preset-skill
version: "1.1"
---
# 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 call the generic **`collect_result`** tool with that handle, which waits
for the image:
```
start = image_generate(prompt="A minimalist bee logo, flat vector, amber on white")
# start.handle == "bg_1"
res = collect_result(handle="bg_1")
# → the real result: {"images":[{"path": …}], "usage": …, …}
# → or {"status":"pending", ...} if a new message arrived first
```
`collect_result` waits until generation finishes. If a new message for you arrives
first it returns `{"status":"pending"}` at once: answer the message, then call it
again with the same handle. It's fine to do other small things before calling it.
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")` — it waits for the real result (call it again if a new message made it return `{"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?"
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |