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 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:

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:

Authorization: Bearer YOUR_LONG_RANDOM_API_TOKEN

or:

x-api-key: YOUR_LONG_RANDOM_API_TOKEN

You can change the server API key without restarting:

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:

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:

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:

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:

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: generic/local API usage.
• API图片绘制及修改-Agent-NAS.md: NAS usage with 192.168.31.5:4000.

Docker Compose Deploy

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

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:

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.