<div align="center">
<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
</div>

# Run and deploy your AI Studio app

This contains everything you need to run your app locally.

View your app in AI Studio: https://ai.studio/apps/96002e3b-5eec-4566-85e8-718714e15c2c

## Run Locally

**Prerequisites:**  Node.js


1. Install dependencies:
   `npm install`
2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
3. Run the app:
   `npm run dev`

## Run the API server

The UI runs on port `3000`. The HTTP API runs separately on port `3002`.

1. Set `GEMINI_API_KEY` and `API_AUTH_TOKEN` in `.env.local` or your shell.
2. Start the API:
   `npm run api`
3. Check the API:
   `http://localhost:3002/api/health`

Example `.env.local`:

```env
GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
API_AUTH_TOKEN="YOUR_LONG_RANDOM_API_TOKEN"
API_PORT="3002"
```

All protected API calls must send one of these headers:

```txt
Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN
```

or:

```txt
x-api-key: YOUR_LONG_RANDOM_API_TOKEN
```

You can change the server API key without restarting:

```bash
curl -X POST http://localhost:3002/api/config/api-key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -d "{\"apiKey\":\"YOUR_GEMINI_API_KEY\",\"persist\":true}"
```

You can also pass a temporary Gemini key for one call:

```bash
curl -X POST http://localhost:3002/api/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -H "x-gemini-api-key: YOUR_GEMINI_API_KEY" \
  -d "{\"prompt\":\"Create a clean product poster\"}"
```

### API examples

Generate or edit with JSON/base64:

```bash
curl -X POST http://localhost:3002/api/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -d "{\"prompt\":\"Create a clean product poster for a white coffee mug\",\"imageSize\":\"1K\",\"aspectRatio\":\"1:1\"}"
```

Upload an image or document with a prompt:

```bash
curl -X POST http://localhost:3002/api/generate/upload \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -F "prompt=Change the background to a bright studio scene" \
  -F "imageSize=1K" \
  -F "aspectRatio=1:1" \
  -F "files=@input.png"
```

Analyze a document:

```bash
curl -X POST http://localhost:3002/api/analyze-document \
  -H "Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN" \
  -F "prompt=Summarize this document in Chinese" \
  -F "files=@report.pdf"
```

API auth is required by default. For local-only development, you can set `API_AUTH_DISABLED=true`, but do not use that on a LAN or server.

For Agent-facing image generation and editing instructions, see `API图片绘制及修改-Agent.md`.

## Docker Compose Deploy

For Docker Compose deployment, edit `docker_compose.yaml` and fill the `environment` values:

```env
GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
API_AUTH_TOKEN="YOUR_LONG_RANDOM_API_TOKEN"
API_AUTH_DISABLED="false"
API_PORT="3002"
APP_PASSWORD="123456"
APP_URL="http://YOUR_SERVER_IP:3000"
```

Then start:

```bash
docker compose -f docker_compose.yaml up -d --build
```

Default ports:

- UI: `http://YOUR_SERVER_IP:3000`
- API: `http://YOUR_SERVER_IP:3002`

For migration steps and port changes, see `迁移部署说明.md`.