---
name: image-2-agent
description: Use Image-2 Agent API to generate AI images, upload reference images, poll async image tasks, or list image task history through user-bound agent tokens. Use when Codex needs to call the local image-2 service as an agent, prepare prompts for Image-2, or help another agent configure IMAGE2_AGENT_BASE_URL and IMAGE2_AGENT_TOKEN.
---

# Image-2 Agent

## Overview

Use the Image-2 service through its Agent API. The API token belongs to an existing Image-2 user account, so every generation uses that user's wallet, VIP discount, reference-image policy, and task history.

## Required Environment

Read these environment variables before calling the API:

- `IMAGE2_AGENT_BASE_URL`: base URL, for example `https://image.example.com` or `http://localhost:3102`.
- `IMAGE2_AGENT_TOKEN`: agent token beginning with `iat_`.

If `IMAGE2_AGENT_TOKEN` is missing and the user can provide an Image-2 username and password, use `scripts/create_token.py` to create a token through the existing account system. The script logs in through `/user/login`, creates a user-bound `iat_...` token through `/user/agent-tokens`, and prints the token once.

**There is no web page or dashboard for issuing agent tokens.** Never tell the user to "go to the website to get a token" — that UI does not exist. Tokens are created only via `scripts/create_token.py` or the `POST /user/agent-tokens` API.

Never send the agent token to `/api/*`, `/user/*`, or `/admin-api/*`. Use it only with `/agent-api/*`.

## Workflow

1. Build a concise image prompt from the user's request.
2. If local reference images must be used, upload them first with `POST /agent-api/uploads/reference` and collect returned URLs.
3. Submit generation with `POST /agent-api/generate`.
4. If the response has `data.type = "sync"` and `data.imageUrl`, return the image URL.
5. If the response has `data.type = "async"` and `data.taskId`, poll `GET /agent-api/status/:taskId` until `completed` or `failed`.
6. Report billing fields when useful: `cost`, `remainingPoints`, and `referenceCost`.

Read `references/agent-api.md` when you need exact request or response schemas.

## Create a Token

Prefer the bundled script when a user wants easy setup:

```bash
python3 scripts/create_token.py \
  --base-url "$IMAGE2_AGENT_BASE_URL" \
  --username "$IMAGE2_USERNAME" \
  --print-env
```

The script prompts for the password if `--password` or `IMAGE2_PASSWORD` is not provided. Do not store passwords in files or include them in shared artifacts.

Use `--json` when another automation needs the full response.

## Error Handling

- `UNAUTHORIZED`, `TOKEN_REVOKED`, `TOKEN_EXPIRED`: ask the user for a valid agent token.
- `FORBIDDEN_SCOPE`: explain which scope is missing.
- `INSUFFICIENT_POINTS`: tell the user the required and current balance from the message.
- `REFERENCE_IMAGE_LIMIT`: reduce reference images or ask the user to choose fewer images.
- `ENDPOINT_NOT_CONFIGURED`: tell the user to configure the upstream endpoint in Image-2 admin.
- `UPSTREAM_FAILED`: summarize the failure and suggest retrying later; do not expose secrets.

## Output Style

Return the final image URL, task ID, and a short status. Do not include raw upstream payloads unless the user is debugging.