# img-infinite-canvas API

Base path: `/api`

## Health

`GET /api/health`

```json
{
  "status": "ok",
  "service": "img_infinite_canvas-api",
  "time": "2026-07-04T03:20:00Z"
}
```

## Dashboard

`GET /api/dashboard`

Returns credits, quick actions, recent projects, and inspiration items for the Moteva-style home screen.

## Agent Starters

`GET /api/ui/agent-starters?locale=zh-CN`

Returns the localized empty-state content used by the canvas Agent panel. The endpoint is public so shared canvases can render the same content. Supported locales are `zh-CN` and `en-US`; unsupported values fall back to `zh-CN`.

```json
{
  "title": "今天想创作什么？",
  "description": "输入提示词开始——或使用下方的起点",
  "previewImages": [
    "https://static.codia.ai/public/images/f788bdcc/lg.webp",
    "https://static.codia.ai/public/images/ec25067a/lg.webp",
    "https://static.codia.ai/public/images/d4ccbe39/lg.webp"
  ],
  "starters": [
    {
      "id": "ecommerce",
      "label": "电商商品图",
      "prompt": "Create a premium ecommerce product image for a portable espresso machine, with realistic lighting, clean composition, benefit callouts, and marketplace-ready visual hierarchy"
    }
  ]
}
```

The full block can be overridden through `AgentStarter` service configuration. `PreviewImages` accepts up to three URLs; each locale owns its ordered `Starters` list. Invalid or empty configured values fall back to the built-in content, preserving the frontend contract until an operations content store replaces the configuration source.

```yaml
AgentStarter:
  PreviewImages:
    - https://cdn.example.com/agent-entry-1.webp
  ZhCN:
    Title: 今天想创作什么？
    Description: 输入提示词开始——或使用下方的起点
    Starters:
      - ID: campaign
        Label: 运营活动
        Prompt: Create a campaign visual for the current promotion
  EnUS:
    Title: What would you like to create today?
    Description: Enter a prompt to begin, or use one of the starting points below.
    Starters:
      - ID: campaign
        Label: Campaign
        Prompt: Create a campaign visual for the current promotion
```

## Auth

Global mode is enabled in `etc/config.yaml`. Email verification codes are stored through the cache abstraction for 10 minutes; with `Cache.Driver: redis`, the code only lives in Redis until TTL or successful consumption.

SMTP is configured under `Auth.Email`:

```yaml
Auth:
  Turnstile:
    Enabled: true
    SiteKey: 1x00000000000000000000AA
    SecretKey: 1x0000000000000000000000000000000AA
    SecretKeyEnv: TURNSTILE_SECRET_KEY
    SiteVerifyURL: https://challenges.cloudflare.com/turnstile/v0/siteverify
    TimeoutSeconds: 5
  Email:
    Driver: smtp # none|smtp
    Host: smtp.example.com
    Port: 587
    Username: user@example.com
    Password: app-password
    FromName: hello
    FromEmail: hello@example.com
    BrandName: Moteva
    UseTLS: false
    StartTLS: true
    TimeoutSeconds: 10
```

When `Auth.Turnstile.Enabled` is `false`, `/api/auth/options` returns `turnstile.enabled=false`; the frontend hides the Cloudflare Turnstile widget and sends email-code requests without a Turnstile token. When enabled, the frontend must submit `turnstileToken`, and the API validates it before creating or emailing a verification code.

`POST /api/auth/global/email-code`

```json
{
  "email": "user@example.com",
  "turnstileToken": "client-widget-token"
}
```

Development response includes an email preview so the frontend can render the same verification flow without a mail provider:

```json
{
  "target": "user@example.com",
  "expiresIn": 600,
  "devCode": "263081",
  "email": {
    "fromName": "hello",
    "fromEmail": "hello@auth.moteva.local",
    "toEmail": "user@example.com",
    "subject": "Welcome to Moteva!",
    "code": "263081"
  }
}
```

`POST /api/auth/global/email-login`

```json
{
  "email": "user@example.com",
  "code": "263081"
}
```

Returns an authenticated session with `accessToken`, `refreshToken`, and the user profile. Project creation, generation, upload, save, and deletion require `Authorization: Bearer <accessToken>`.

`POST /api/auth/global/google-login`

```json
{
  "idToken": "google-id-token"
}
```

`POST /api/auth/china/wechat-login`

First QR callback:

```json
{
  "code": "wechat-oauth-code",
  "state": "signed-state"
}
```

If the WeChat identity is already bound to a phone number, the response is authenticated. If not, the response has `status: "phone_binding_required"` and a short-lived `bindingToken`.

Phone binding step:

```json
{
  "bindingToken": "signed-binding-token",
  "phone": "13800138000",
  "countryCode": "+86",
  "smsCode": "123456"
}
```

After binding succeeds, later QR logins use only `code` and `state`.

## Account

All account endpoints require `Authorization: Bearer <accessToken>`. Cookie auth and the legacy `token` header are not used. Account profile state is owned by the auth module and persisted in PostgreSQL or the configured in-memory store.

`GET /api/account/profile`

Returns the current authenticated user.

`PATCH /api/account/profile`

```json
{
  "name": "Xu Liang",
  "avatarUrl": "https://cdn.example.com/avatar.webp"
}
```

Updates account display name and avatar URL. The frontend uploads avatar files through `/api/assets/upload-url` first, then stores the returned public URL on the profile.

`GET /api/account/devices`

Returns every non-revoked, non-expired web session for the authenticated account. The current session is listed first, followed by most recently active sessions.

```json
{
  "devices": [
    {
      "id": "62dc9af7-e44a-4f47-a0bc-b3408d17c33f",
      "online": true,
      "current": true,
      "deviceType": "desktop",
      "system": "macOS",
      "browser": "Chrome 126",
      "client": "PC-WEB",
      "lastSeenAt": "2026-07-11T09:00:00Z"
    }
  ],
  "limits": {
    "desktop": 2,
    "mobile": 1
  }
}
```

`limits` is sourced from `Auth.DeviceLimits.Desktop` and `Auth.DeviceLimits.Mobile` in service configuration. It is returned with the device list so clients display the effective policy without hard-coded counts. Defaults are 2 desktop web sessions and 1 mobile web session.

The limits are enforced independently by normalized device type. Session creation and same-type overflow revocation run in one atomic store operation. When a new login exceeds a limit, the newest login remains active and the oldest same-type session is revoked immediately. Device listing also reconciles sessions created before this enforcement was deployed, preserving the current session first.

Each signed access and refresh token carries an opaque random session ID. Bearer authentication validates that server-side session before accepting the token, so revoked sessions stop working immediately. Device metadata is derived from request headers for display only and is never an authorization signal. A session is reported online when it is current or was active during the previous five minutes.

`lastSeenAt` is an RFC3339 UTC instant. Clients must render it in the browser's local timezone rather than displaying the UTC wire representation directly.

Valid legacy access tokens without a session ID are migrated to a revocable server-side session on first use after their user subject is verified. This preserves existing logins during rollout.

`DELETE /api/account/devices`

Atomically revokes every active session for the account except the current session. Returns the number of sessions revoked:

```json
{
  "removed": 2
}
```

`POST /api/account/logout`

Revokes the current server-side session and returns `{"removed": 1}` when it was active. The frontend then clears its locally stored token. Other device sessions remain signed in.

## Projects

Brand Kit selection is optional on project creation. Omit `brandKitId` to apply the authenticated user's default Brand Kit, send an empty string to explicitly use no Brand Kit, or send a user-owned Brand Kit ID.

`GET /api/projects`

Returns all project summaries, sorted by `updatedAt` descending.

`POST /api/projects`

```json
{
  "title": "still day 官网",
  "prompt": "为 still day 品牌服装独立站设计官网视觉方向",
  "brandKitId": "brand-kit-core",
  "imageModel": "gpt-image-2",
  "imageSize": "1024x1024",
  "imageQuality": "auto",
  "imageCount": 1,
  "enableWebSearch": true
}
```

`enableWebSearch` only opens the web-search capability. The agent model still decides per request whether search is actually needed; if it is not needed, no web-search step is recorded. When search runs, result titles, URLs, snippets, and cleaned page-content excerpts are stored for the agent.

`GET /api/projects/:id`

Returns the full project, including `brandKitId`, viewport, nodes, connections, and agent messages. Compiled Brand Kit instructions and uploaded assets remain server-side and are never accepted from the client as authoritative prompt context.

`POST /api/canva/project/queryProject`

```json
{
  "projectId": "project-id",
  "cid": "1781596271730ngdozsck"
}
```

Returns a Lovart-style project document with `assetMeta`, compressed `canvas`, `validProjectId`, `projectType`, `version`, and permission metadata. The frontend uses this for lightweight project opening, then decodes the `SHAKKERDATA://` canvas locally.

`PATCH /api/projects/:id/title`

```json
{
  "title": "夏季活动主视觉"
}
```

Renames the infinite canvas project and updates `updatedAt`.

`PATCH /api/projects/:id/brand-kit`

```json
{
  "brandKitId": "brand-kit-core"
}
```

Only the project owner can change this binding. The ID must belong to the authenticated user. Send `{"brandKitId":""}` to remove the Brand Kit from the canvas without deleting it.

`DELETE /api/projects/:id`

Deletes the project record. PostgreSQL cascades canvas nodes, chat messages, history, and connections; after the database delete succeeds, image assets referenced by the canvas and generated-file history are queued for asynchronous OSS deletion.

## Brand Kits

All Brand Kit endpoints require `Authorization: Bearer <accessToken>`. Data is scoped to the authenticated user ID; IDs owned by another user are returned as not found.

`GET /api/brand-kits`

Returns the user's Brand Kits, newest first:

```json
{
  "brandKits": [
    {
      "id": "brand-kit-core",
      "name": "Core Brand",
      "document": "{\"version\":1,\"id\":\"brand-kit-core\",\"name\":\"Core Brand\",...}",
      "isDefault": true,
      "createdAt": "2026-07-10T08:00:00Z",
      "updatedAt": "2026-07-10T08:15:00Z"
    }
  ]
}
```

`PUT /api/brand-kits/:id`

Creates or replaces a version-1 Brand Kit document. The document supports brand foundation, voice, grouped colors, uploaded fonts with optional sizes and descriptions, logos, an optional cover, reference images, and reusable visual direction.

```json
{
  "document": "{\"version\":1,\"id\":\"brand-kit-core\",\"name\":\"Core Brand\",\"brandName\":\"Moteva\",\"tagline\":\"\",\"summary\":\"Creative workspace\",\"audience\":\"Design teams\",\"positioning\":\"\",\"personality\":\"Clear\",\"voice\":{\"traits\":\"Direct\",\"guidance\":\"Lead with outcomes\",\"sample\":\"Move with clarity\"},\"logos\":[],\"colorGroups\":[],\"typography\":[],\"referenceImages\":[],\"visual\":{\"keywords\":\"Precise\",\"composition\":\"\",\"imagery\":\"\",\"dos\":\"\",\"donts\":\"\",\"prompt\":\"\"},\"applyToNewProjects\":true,\"createdAt\":\"\",\"updatedAt\":\"\"}",
  "isDefault": true
}
```

At most one Brand Kit is default per user. The server canonicalizes timestamps and default state rather than trusting those fields inside `document`.

`DELETE /api/brand-kits/:id`

Deletes the owned Brand Kit. Existing project bindings are cleared; projects and canvas content remain intact.

For every Agent Chat turn, new thread, planner request, and image generation, the server resolves the currently bound Brand Kit again. Text rules become binding creative context, while uploaded logos, cover images, and visual references are appended after any user-supplied reference images.

## Sharing and access control

Sharing uses a separate authorization policy from project ownership. Effective access is resolved in this order: owner, explicit email/phone member, then link permission.

- `canvas`: canvas document only; messages and agent endpoints are unavailable.
- `viewer`: canvas and chat history are readable, but every mutation is denied.
- `editor`: viewer access plus canvas/agent mutations; authentication is mandatory.
- `owner`: editor access plus share administration and project deletion.

Share IDs are 27-character, case-sensitive base62 values generated from cryptographic randomness. The database stores a SHA-256 lookup hash and AES-GCM ciphertext rather than a plaintext link credential. Supply `SHARING_ENCRYPTION_SECRET` through the deployment secret manager; when omitted, local development falls back to `Auth.TokenSecret`.

All management endpoints require `Authorization: Bearer <accessToken>` and verify project ownership:

- `GET /api/projects/:id/sharing` returns link permission, authorized people, owner information, and visitor count.
- `PUT /api/projects/:id/sharing/link` accepts `private`, `canvas`, `viewer`, or `editor`.
- `POST /api/projects/:id/sharing/members` accepts an email/phone `identifier` and a `canvas`, `viewer`, or `editor` permission. Identifiers are normalized and unique per project; inviting the owner returns `share.self_invite`, while inviting an existing member returns `share.member_exists` (both HTTP `409`).
- `PATCH /api/projects/:id/sharing/members/:memberId` changes a member permission.
- `DELETE /api/projects/:id/sharing/members/:memberId` removes one member.
- `GET /api/projects/:id/sharing/visitors` lists deduplicated visitors and visit counts.
- `DELETE /api/projects/:id/sharing/access` removes the policy, members, and visitors; the old link immediately fails on the next request.

Example invite:

```json
{
  "identifier": "editor@example.com",
  "permission": "editor"
}
```

`GET /api/shares/:shareId` is the public bootstrap. `Authorization` is optional for `canvas`/`viewer`, mandatory for `editor`, and used to resolve explicit member access. Clients send a random installation-scoped `X-Share-Visitor` value for visitor deduplication.

```json
{
  "shareId": "XhRewKnS4it7X9kEMFLcdVJentg",
  "project": { "id": "project-id", "nodes": [], "messages": [] },
  "access": {
    "permission": "canvas",
    "source": "link",
    "authenticated": false,
    "isOwner": false,
    "capabilities": {
      "canViewCanvas": true,
      "canViewChat": false,
      "canEdit": false,
      "canManage": false
    }
  }
}
```

Subsequent shared project requests send `X-Share-Id: <shareId>`. Middleware re-resolves access, binds it to the exact project ID, and only then creates an internal owner-scoped repository context. Client-supplied `X-User-Id` is ignored.

## Agent Chat

`POST /api/projects/:id/agent/chat`

```json
{
  "messages": [
    {
      "role": "user",
      "contents": [{ "type": "text", "text": "继续优化首页首屏，但保留品牌色" }]
    }
  ],
  "enableWebSearch": false,
  "imageModel": "gpt-image-2",
  "imageSize": "1024x1024",
  "imageQuality": "auto",
  "imageCount": 1,
  "mode": "design"
}
```

The harness builds short memory from the current turn, recent messages, and visible canvas state, and long memory from durable project decisions, prior artifacts, and previous research records with page-content excerpts. Image titles and assistant language are generated from the request context instead of fixed model labels.

## Generate

`POST /api/projects/:id/generate`

```json
{
  "prompt": "继续扩展产品详情页模块",
  "mode": "design"
}
```

Returns the updated project, the assistant message, and generated nodes.

The generation path uses the configured design agent runner. The default is the `sky-valley/pi` Go agent adapter, with local desktop/MCP agent behavior disabled.

## Image Node Actions

`POST /api/projects/:id/nodes/:nodeId/actions/async`

Visual annotation edits keep the selected clean image as the base and provide a second uploaded guide image containing numbered brush, circle, rectangle, or cross marks. Each number maps to an editable instruction in `prompt` and the normalized geometry in `selection`. The model must use the guide only for location and must not render marks or numbers into the result.

```json
{
  "action": "visual-annotation",
  "prompt": "1. Cross: remove the chest logo\n2. Rectangle: change the trousers to navy",
  "imageModel": "gpt-image-2",
  "imageSize": "1024x1024",
  "annotationImage": "https://cdn.example.com/annotation-guide.png",
  "selection": "{\"annotations\":[{\"index\":1,\"type\":\"cross\",\"instruction\":\"remove the chest logo\",\"points\":[{\"x\":0.42,\"y\":0.28},{\"x\":0.58,\"y\":0.5}]}]}"
}
```

`annotationImage` and a non-empty `prompt` are required for `visual-annotation`. The original node remains unchanged. Submission creates a generating copy 32 canvas units to its right, and the completed image replaces only that copy through the standard asynchronous event lifecycle.

## Generator Tasks

`POST /api/generator/tasks`

```json
{
  "cid": "client-request-id",
  "project_id": "project-id",
  "generator_name": "layer-separation",
  "input_args": {
    "image_url": "https://cdn.example.com/source.png"
  }
}
```

`layer-separation` returns a task id that can be polled with `GET /api/generator/tasks?task_id=<id>&project_id=<project-id>`. The service separates the source into a clean background, foreground image artifacts with `bbox`, and a `text_render_data` artifact for editable text reconstruction. It does not request PSD from the image-generation API; that API only produces raster image formats.

The canvas `edit-elements` node action uses the same separation path but writes the separated result beside the original image. The original image remains unchanged; a transparent frame contains the clean background at the bottom, followed by separated foreground images and editable text layers. Users can export that frame as PSD from the canvas context menu; the browser builds the PSD from the current canvas layers at download time.

## Chat History Replay

`GET /api/projects/:id/history`

Returns replayable assistant/user chat history for the project.

```json
{
  "projectId": "project-id",
  "messages": []
}
```

Lovart-style agent thread endpoints are also available:

`POST /api/canva/agent/queryAgentLastThread`

Returns `{ "code": 0, "msg": null, "data": "<thread-id>" }`.

`POST /api/canva/agent/agentThreadList`

Accepts `{ "projectId": "project-id", "page": 1, "pageSize": 100, "cid": "..." }` and returns paginated thread summaries.

`GET /api/canda/chat-history?thread_id=<thread-id>&project_id=<project-id>`

Returns Lovart-style thread history items grouped by `thread_meta`.

`GET /api/canda/thread/status?thread_id=<thread-id>&project_id=<project-id>`

Returns `{ "code": 0, "msg": "success", "data": { "status": "done" } }` or the current project thread status when `project_id` is present.

## Save Canvas

`POST /api/canva/project/saveProject`

`PATCH /api/projects/:id/canvas`

```json
{
  "canvas": "SHAKKERDATA://<gzip-base64-canvas-snapshot>",
  "projectCoverList": ["https://cdn.example.com/canvas/image.png"],
  "picCount": 1,
  "projectName": "Untitled",
  "projectId": "project-id",
  "version": "1783472149000",
  "sessionId": "browser-session-id",
  "canvasV2Gray": true
}
```

```json
{
  "code": 0,
  "msg": null,
  "data": {
    "projectId": "project-id",
    "newCreated": false,
    "validProjectId": true,
    "version": "1783498482000"
  }
}
```

Saves canvas layout changes with a Lovart-style lightweight payload. The frontend posts to `/api/canva/project/saveProject`; `/api/projects/:id/canvas` remains as a compatibility route. The `canvas` value is a `SHAKKERDATA://` gzip+base64 encoded snapshot containing viewport, nodes, and connections. Legacy uncompressed `{ "viewport": ..., "nodes": ..., "connections": ... }` payloads are still accepted.

When a canvas image node disappears from the saved node list, its backing OSS asset is queued for asynchronous deletion after the canvas save succeeds.

## Image Asset Upload

`POST /api/assets/upload-url`

```json
{
  "fileName": "reference.png",
  "contentType": "image/png",
  "size": 123456
}
```

Returns a signed upload URL for the configured storage backend.

Supported drivers:

- `memory`
- `minio`
- `s3` / `aws`
- `r2`
- `aliyun`

## Errors

JSON error response:

```json
{
  "error": "project not found",
  "code": 404
}
```

Common status codes:

- `400`: invalid input
- `404`: project not found
- `500`: internal server error