---
name: gen-image
description: |
  AI image generation skill: produce an image from a text prompt, or do image-to-image with reference images. Backed by ab-api's `/model/genImg` (the Seedream 5.0 family).

  Use this skill immediately whenever the user asks for any of:
  - AI image generation, text-to-image, "draw me ...", "generate an image of ..."
  - Image-to-image, reference image, style transfer, image variation
  - Generate an image with Doubao / Seedream
  - Provide a prompt and ask for an image

  Even without an explicit "use AI", any request that turns a description into an image should route here.
triggers:
  - AI image generation, text-to-image, "draw me ...", "generate an image of ..."
  - Image-to-image, reference image, style transfer, image variation
  - Generate an image with Doubao / Seedream
  - Provide a prompt and ask for an image
---

# AI Image Generation Skill

Wraps ab-api's `POST /model/genImg` (the same endpoint the web studio uses), authenticated with the **Tianyan privateToken**, routed through LiteLLM to the **Seedream 5.0** family.

## Models and sizes

Pass `--model` a short name. The authoritative roster — ids, aliases, per-model limits —
lives in the backend catalog (`/model/capabilities`), which the CLI fetches at runtime;
the names below are the stable aliases to use.

| `--model` | What it is | Reference images |
|-----------|------------|------------------|
| `seedream` | Default. General-purpose, highest output resolution. | up to 14 |
| `seedream-pro` | High-fidelity variant: better placement/element control, more faithful text rendering. Costs more per image. | up to 10 |

- **Seedream**: `--size` is an aspect ratio (e.g. `1:1`, `9:16`) or `WxH`. The backend maps the
  ratio to that model's own pixel preset and rescales out-of-range sizes, so prefer a ratio
  over explicit pixels.
- **`seedream-pro`** additionally supports `3:2` / `2:3` / `21:9`, and caps output at ~2K
  (about 4.6 MP). Asking it for 4K pixels gets scaled down, not rejected — use `seedream`
  when you need a genuinely larger image.
- **`--resolution`** is inert today: it only ever applied to Gemini, which is not wired up on
  the gateway. Control image dimensions with `--size`.

## Auth & environment

No skill-local env file — the executing process inherits the system environment.

- **Enterprise OpenClaw**: auth is already injected, **no need** for `PRIV_TOKEN` / `--priv-token`.
- **Other environments**: configure the token. Without a token, non-interactive runs fail; interactive ones may prompt.

| Env var | Description | Default |
|---------|-------------|---------|
| `PRIV_TOKEN` | Tianyan token; `--priv-token` overrides | none |
| `MM_IMAGE_MODEL` | Default model, as a `--model` value | backend default (`seedream`) |
| `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `https://api.remixmate.ai/api` |
| `AGENT_NAME` | Optional `x-invoke-agent` header | none |

## Operations

> This skill was migrated from a Python script to an remixmate CLI HTTP handler (`entry.type: http`). The agent invocation is unchanged (same tool name `gen_image`, same params as in `skill.json`); local repro goes through `remixmate gen-image ...`.

1. **Prompt**: be specific about subject, style, lighting, composition. Either English or Chinese works.
2. By default only the URL is printed (good for showing to the user); the legacy local-download flag has been dropped — image URLs are persisted in the cloud.

### Text-to-image

```bash
remixmate gen-image \
  --prompt "<image description>" \
  --size "9:16"
```

```bash
# High-fidelity: precise placement, legible on-image text
remixmate gen-image \
  --prompt "<image description>" \
  --model seedream-pro \
  --size "16:9"
```

### Image-to-image (reference image)

Reference images accept local file paths, HTTPS URLs, or data URIs. Pass `--reference` multiple times for multiple references.

- **`seedream`**: up to **14** reference images, `--image-strength` controls reference influence.
- **`seedream-pro`**: up to **10** reference images. Best choice when the edit has to land in a
  specific spot — describe the target region in the prompt (e.g. "in the marked area at the
  bottom left") and it holds position far better than `seedream`.

Over-the-limit runs fail fast in the CLI, before spending credits.

```bash
# URL reference
remixmate gen-image \
  --prompt "Convert this photo to an oil-painting style" \
  --reference "https://example.com/photo.jpg"
```

```bash
# Local-file reference + reference strength
remixmate gen-image \
  --prompt "Match the style of this reference" \
  --reference ./ref.png \
  --image-strength 0.6
```

```bash
# Multiple references
remixmate gen-image \
  --prompt "Blend these styles" \
  --reference ./a.png \
  --reference ./b.png
```

3. **Surface results**: stdout prints one image URL per line; show them directly to the user.

## Common CLI flags

| Flag | Description | Default |
|------|-------------|---------|
| `-p` / `--prompt` | Description (required) | — |
| `-m` / `--model` | `seedream` / `seedream-pro` | see `MM_IMAGE_MODEL` |
| `-s` / `--size` | Aspect ratio or WxH | `1:1` |
| `-n` | Number of images, 1–4 | `1` |
| `-g` / `--guidance-scale` | Guidance scale (when supported) | backend default |
| `--reference` | Reference image (repeatable; local path / URL / data URI) | none |
| `--image-strength` | Reference strength 0–1 | backend default |
| `--negative-prompt` | Things to avoid | none |
| `--seed` | Random seed (reproducibility) | none |
| `--watermark` | Add a watermark (no `--no-watermark` opt-out) | backend default |
| `--api-base-url` | Override API root | see above |
| `--priv-token` | Override token | see above |

## Credits

Every run charges credits, per image and **per model** — `seedream-pro` costs noticeably more
per image than `seedream`, so don't reach for it by default. The CLI prints a footer on stdout
when it charges:

```
💳 Charged 31 credits · balance 1,240
```

Relay it to the user whenever it appears — it is the only signal they get about what a
generation cost, and the balance is the only warning before a run fails with
`insufficient_credits`. Do not drop it from your summary.

## Error handling

- **401** / **token missing** (non-OpenClaw): set `PRIV_TOKEN`.
- **Business `code != 0`**: read `msg` on stderr.
- **429**: rate-limited; retry later.
- **Network**: verify connectivity and `MM_API_BASE_URL`.