# 应用名称与图标

在桌面点击「管理应用」，再选择用户应用进入编辑；应用市场的已安装列表也提供编辑入口。可以修改名称、应用描述、设计理念，上传图标或重新生成。应用 ID、slug、源码和数据集绑定保持不变。

## 图片模型配置

在桌面「设置」的「大模型」和「图片生成模型」两个 tab 中分别配置对话模型和图片生成模型，切换 tab 时保留尚未保存的输入。对话模型负责把应用用途、目标用户和设计理念转换为视觉方案；图片模型使用内置 [ip-as-logo](https://github.com/s1dashu/ip-as-logo-skill) 提示词绘制一张图片。图标风格以简单、圆润、可识别的角色为主。

支持以下协议，模型名称需要填写服务商实际提供的图片模型 ID：

| 协议 | 接口地址示例 | 调用路径与返回格式 |
| --- | --- | --- |
| OpenAI Images 兼容 | `https://api.openai.com/v1` | `POST /images/generations`；读取 `data[0].b64_json` 或 `data[0].url`。 |
| 火山引擎 Seedream | `https://ark.cn-beijing.volces.com/api/v3` | 火山方舟 Ark：`POST /images/generations`，Bearer API Key；读取 `data[0].b64_json` 或 `data[0].url`。 |
| Gemini 原生 | `https://generativelanguage.googleapis.com/v1beta` | `POST /models/{model}:generateContent`；读取 `candidates[0].content.parts[].inlineData.data`。 |

OpenAI 协议默认不传 `size`，通过提示词要求正方形。也可以选择 `1024x1024` 或 `1536x1536`，需要模型明确支持该尺寸。Gemini 使用 `aspectRatio: "1:1"`，由模型选择原生分辨率。平台不缩放生成结果，也不会根据画面风格自动重试。

### 火山引擎 Seedream

接口协议选择「火山引擎 Seedream」，填写火山方舟控制台中已开通的 Seedream Model ID，或者 `ep-` 开头的推理接入点 ID，以及对应的 **方舟 API Key**（不是火山引擎 Access Key / Secret Key）。默认地址已经预填；如果粘贴完整 `/images/generations` 地址，保存时会自动转为基础地址。

默认 `2048x2048`，还可以选择 `1024x1024`、`3072x3072` 和 `4096x4096`，具体以所选模型支持的尺寸为准。平台固定发送 `sequential_image_generation: "disabled"`、`stream: false`、`response_format: "b64_json"` 和 `watermark: false`，每次只生成一张图片，不发送 OpenAI 的 `n` 参数。生成结果最大 8MB；超过限制时保留原图标并报告错误。

已确认 `doubao-seedream-5-0-260128` 至少需要 3,686,400 像素；填写此 Model ID 时不会提供 1024 × 1024 选项，保存和生成前也会校验。已有的不兼容配置会显示具体提示，需要明确选择新尺寸并保存；不会自动提高分辨率后重新请求。对于无法从名称识别实际模型的 `ep-` 接入点，尺寸限制由方舟校验，已识别的像素下限错误会转换为具体提示。

此选项接入方舟 Ark 图片生成 API，不适用于火山引擎其他需要 AK/SK 签名的视觉服务接口。参数依据[火山引擎官方 SDK](https://github.com/volcengine/volcengine-python-sdk/blob/master/volcenginesdkarkruntime/resources/images/images.py)。

保存 API Key 后不会返回明文；留空保留原 Key，更换接口地址或协议时必须重新填写。移除图片模型设置会停止后续生成，已有图标仍然保留。当前凭证存储在服务端 D1，与对话模型设置采用相同存储方式。

创造模式的 `create_app` 会接收 `description` 和 `design_brief` 并自动生成图标。未配置图片模型或生成失败时，应用仍然创建成功；Agent 会收到独立的 `icon_generation` 状态，用户可以稍后在编辑入口重新生成。

## 编辑应用资料

以下 HTTP API 供宿主或开发工具使用，要求登录态，仅能操作当前用户自己的应用。用户应用内部仍然只使用 `platform.*`，目前没有图标生成 JSB。

`PATCH /api/apps/:id` 修改元数据，返回更新后的 `AppRecord`。

```json
{
  "name": "习惯伙伴",
  "description": "帮助忙碌的人记录每日习惯",
  "design_brief": "友好的小猫形象，柔和的紫色背景",
  "expected_updated_at": "从 GET /api/apps 返回的 updated_at 原样传入"
}
```

`name` 最多 80 字且不能为空；`description` 和 `design_brief` 各最多 2000 字。省略的字段保持原值。`expected_updated_at` 必填；版本过期返回 HTTP 409，请重新读取后修改。显示名称以平台元数据为准，源码包内 `app.json` 不会被自动改写。

`GET /api/apps` 和 `GET /api/apps/:id` 返回 `description`、`design_brief` 和 `icon_url`。`icon_url` 为需要登录态的相对 URL，没有图标时为 `null`。修改图标后 URL 中的版本会改变。

## 上传和读取图标

- `PUT /api/apps/:id/icon`：请求体直接传入图片二进制，`Content-Type` 使用 `image/png`、`image/jpeg` 或 `image/webp`。最大 8MB，校验文件签名和类型，拒绝 SVG。成功返回 `AppRecord`。
- `GET /api/apps/:id/icon`：返回当前图标的二进制数据。使用私有缓存与 `nosniff`；无图标或无权访问时返回 HTTP 404，未登录返回 HTTP 401。

图标保存在独立 R2 路径中，更新应用文件包不会删除图标。上传长方形图片时，桌面按正方形裁切展示，存储文件保持原样。

## 重新生成

`POST /api/apps/:id/icon/generate`，传入 JSON 对象，使用已保存的资料时传 `{}`。可选 `description`、`design_brief` 为本次生成的临时上下文，不会修改已保存的资料。界面会先保存用户修改的资料，再发起生成。

成功返回更新后的 `AppRecord`，并附带 `icon_generation: { status: "generated", model, provider }`。接口会等待生成完成，可能需要几分钟。对话模型方案请求最多等待 60 秒，图片请求最多等待 180 秒；没有图片、格式不支持或服务商错误均返回错误，并保留原图标。

同一应用生成期间重复请求返回 HTTP 409。生成期间上传新图标时，以上传结果为准，旧生成任务不会覆盖它。失败请求不会自动重试，也不会切换模型。上游返回图片 URL 时，平台通过公开 HTTPS 地址下载到 R2，不依赖服务商临时链接长期展示。

## 官方默认模型

设置的两个 Tab 都提供「官方默认 / 自定义」选项。官方大模型为 DeepSeek Flash（`deepseek-flash`），用于对话、应用构建和图标设计方案；官方图片模型为火山方舟 Seedream 5.0（`doubao-seedream-5-0-260128`），每次生成一张 2048 × 2048 的图标。新用户无需填写密钥。

`GET /api/settings/llm` 返回相同的 `source`、`official`、`base_url`、`model`、`has_key` 字段。`PUT /api/settings/llm` 接受 `{ source: "official" }`，或 `{ source: "custom", base_url, model, api_key? }`。省略 `source` 的旧客户端请求仍按自定义配置处理。自定义密钥留空时保留原密钥；修改接口地址必须重新填写密钥。

官方凭据只保存于服务端 Secret，任何设置响应均不返回密钥。切换来源不会删除已保存的自定义配置；官方模型暂不可用时返回明确错误，不会静默使用另一套凭据。

## 设置 API

- `GET /api/settings/images`：返回 `{ source, official: { label, model, available }, provider, base_url, model, size, has_key }`。`source` 为 `official` 或 `custom`；顶层连接参数和 `has_key` 描述用户自己的配置，`official` 只包含官方模型的公开信息。新用户默认选择官方模型，已有自定义配置的用户保持原选择。
- `PUT /api/settings/images`：传入 `{ source: "official" }` 使用官方模型，不需要 API Key，且保留已有自定义配置。选择自定义时传入 `source: "custom"` 和 `provider`（`openai`、`gemini` 或 `seedream`）、`base_url`、`model`、可选 `api_key` 和 `size`（OpenAI / Gemini 默认 `auto`；Seedream 默认 `2048x2048`，传入 `auto` 也会转为此尺寸），返回公开设置。
- `DELETE /api/settings/images`：删除当前用户的图片模型配置和 Key，恢复官方默认并返回公开设置。

接口地址必须使用公开 HTTPS 地址；本地开发环境允许 HTTP localhost 接口用于测试。地址不能包含账号密码、查询参数或片段。

目前尚未提供候选图批量生成、图标历史选择界面、独立后台任务进度 API。每次明确生成只请求一张图片，不会自动生成六张。