# 88API Image Studio for DeepSeek Harness

[中文](README.zh.md) | English

One image studio replaces separate Image2 and Nano Banana plugins. Generate and edit images in DSH with four 88api.ai models, text-to-image, ordered multi-reference editing, 2K/4K output, sequential batches, and a persistent default model—all behind one Key and one install.

88API Image Studio exposes three model-facing tools:

- `image_generate_88api` generates or edits images.
- `image_model_88api` lists models, reads the current default, or changes that default after an explicit user request.
- `image_key_88api` inspects, saves, or clears the Key when a user explicitly asks the Agent to configure it.

The plugin follows the current DSH/Cordis bundle contract. It does not depend on the draft Community Fabric manifest.

## Models and routing

| Model | Family | Protocol | Resolution |
| --- | --- | --- | --- |
| `gpt-image-2` | Image2 | OpenAI Images API | fixed 2K |
| `gpt-image-2-4k` | Image2 | OpenAI Images API | fixed 4K |
| `gemini-3.1-flash-image` | Nano Banana | OpenAI Chat Completions | 1K / 2K / 4K |
| `gemini-3-pro-image` | Nano Banana | OpenAI Chat Completions | 1K / 2K / 4K |

The factory default is `gpt-image-2`. A saved user default overrides it. A model supplied for one generation overrides the default only for that call. The plugin never silently switches models, providers, or protocols.

## Install

Install from GitHub into the profile you actually use:

```sh
dsh plugin --profile web add github:blackdm666/dsh-plugin-88api-image
```

For DSH Desktop, replace `web` with the active Desktop profile name when needed. For reproducible installations, pin a reviewed commit:

```sh
dsh plugin --profile web add github:blackdm666/dsh-plugin-88api-image#<commit-sha>
```

This repository ships runnable JavaScript, so a GitHub install does not need a `prepare` build or pnpm `allowBuilds` permission.

Verify the bundle layer before booting:

```sh
dsh --profile web --dump-config
```

The dump should contain the `88api-image` row.

## Configure the Key: recommended safe method

Run this complete command:

```sh
dsh plugin --profile web exec 88api-image set-key
```

> **Do not paste the Key yet and do not replace any command text. This complete command only opens Key setup; no part of it is the Key.**

Follow these steps in order:

1. Run the complete `dsh plugin --profile web exec 88api-image set-key` command unchanged, then press Enter once.
2. Wait for the terminal to display `88API Key:` on a separate line.
3. Only then paste the real Key and press Enter again. Hidden input is expected.

`dsh plugin` invokes plugin management, `--profile web` selects the profile, `exec` runs an installed command, `88api-image` is this plugin's CLI, and `set-key` enters Key setup mode. Replace only `web` when a different profile is active; never replace `88api-image`, `set-key`, or another command part with the Key.

After running it, the terminal displays `88API Key:`. Paste the real Key only at that prompt and press Enter. Input is hidden and the complete Key does not enter the command-line arguments.

For non-interactive setup, pipe the Key through standard input:

```sh
printf '%s' "$API88_KEY" | dsh plugin --profile web exec 88api-image set-key --stdin
```

Inspect the masked configuration:

```sh
dsh plugin --profile web exec 88api-image config
```

The default config file is `~/.dsh/88api-image/config.json`. `API88_KEY` overrides the saved Key without writing it to disk. Never commit, paste into an issue, or pass a real Key as a command-line argument.

## Configure the Key: ask the Agent to do it

A beginner may say:

```text
My 88API Key is <paste the real Key here>. Save it with image_key_88api. Do not repeat the complete Key; report only the masked preview and whether setup succeeded.
```

The Agent calls `image_key_88api` with `action=set`; the result contains only a masked preview such as `abcdef...1234`.

**Privacy warning:** this is convenient, but a Key sent to the Agent may remain in DSH conversation and tool-call history. Hidden terminal input is recommended for long-term personal use. If a Key was posted in chat, consider deleting that session or rotating the Key in the 88api.ai console afterward.

## Choose and change the default model

Ask the agent in natural language:

```text
List the available 88API image models.
Set my default image model to gemini-3.1-flash-image.
Generate a 16:9 product hero image with my default model.
Use gpt-image-2-4k for this image only; do not change my default.
```

Or set it from the terminal:

```sh
dsh plugin --profile web exec 88api-image set-default gemini-3-pro-image
```

The Agent may call `set_default` only when the user explicitly asks for a long-term change. Ordinary generations omit the model and use the saved default exactly.

## Generation and editing

`image_generate_88api` accepts:

- one `prompt`, optionally repeated with `count` from 1 to 4;
- or `prompts`, up to 20 different sequential paid requests;
- an optional explicit `model` for one call;
- `aspect` and provider-valid `resolution`;
- ordered local `reference_images`, which change the route to image editing;
- `dry_run: true`, which validates and prints sanitized request plans without a Key or paid request.

Image2 uses `/v1/images/generations` or `/v1/images/edits`. Nano Banana always uses `/v1/chat/completions` with `modalities: ["text", "image"]` and `extra_body.google.image_config`.

Generated files are saved under `~/Pictures/88api-image` by default. If the active DSH model declares image input and an attachment service is mounted, the plugin also attaches the generated image to the tool result. Otherwise it returns the absolute saved path without injecting an image into a text-only model route.

## Cost and retry safety

Each `count` or `prompts` item is an independent paid request. Batches run sequentially and stop on the first failure.

Errors marked `[NO-AUTO-RETRY]` mean the request was accepted or its cloud state is unknown. The plugin never automatically retries such a request or falls back to another model. Report the possible charge and wait for explicit user authorization before submitting a new paid request.

## Security model

DSH plugins run as trusted local code in the Host process; capability metadata is not a sandbox. Review the source and pin a commit before installation. This plugin:

- keeps DSH core packages as peer dependencies to avoid duplicate Cordis/tool runtimes;
- stores the Key with restrictive file permissions where the platform supports them;
- masks the Key in all summaries;
- caps reference and response bytes;
- requires HTTPS for the API base URL unless a deployment explicitly opts into an insecure local test endpoint;
- refuses non-HTTPS, local, or private-network image URLs returned by an upstream response;
- does not send the Key to redirected or third-party image hosts.

## Current scope

Version 0.1 focuses on unified text-to-image, multi-reference editing, repeated outputs, sequential prompt batches, dry runs, persistent model selection, and DSH attachment rendering. It does not yet port the older Codex-only SSE preview, folder/template workflow, repair-pass, or nail stress-test commands.

## Development

```sh
npm install
npm run check
npm run self-test
```

The test suite uses only local mock servers and never calls a paid 88API endpoint. CI also packs the bundle, installs the tarball into a clean DSH profile, and verifies the composed config.

License: [MIT](LICENSE).