@henjicc/ai-sdk 0.9.0 → 0.10.0

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206/KIE.md

@@ -1,131 +1,159 @@
-# KIE · 供应商基础文档
-
-| 项目 | 内容 |
-|---|---|
-| 最后更新 | 2026-08-22 |
-| 供应商类型 | 聚合中转（非模型原厂） |
-| 项目内 `providerId` | `kie` |
-| 生成 Base URL | `https://api.kie.ai` |
-| 上传 Base URL | `https://kieai.redpandaai.co` |
-| 鉴权 | `Authorization: Bearer <API Key>` |
-| 任务模式 | Market 模型统一异步任务 |
-| 文档/价格可见性 | 公开，无需登录；API Key 和账单需登录 |
-
-## 1. 基础端点
-
-| 用途 | 方法与路径 | 说明 |
-|---|---|---|
-| 创建 Market 任务 | `POST /api/v1/jobs/createTask` | body 为 `model` + `input`，可选 `callBackUrl` |
-| 查询 Market 任务 | `GET /api/v1/jobs/recordInfo?taskId=...` | 所有 Market 模型的统一查询入口 |
-| 查询剩余积分 | `GET /api/v1/chat/credit` | 返回 `data` 整数积分 |
-| 换取生成文件下载链 | `POST /api/v1/common/download-url` | 仅接受 KIE 生成文件 URL |
-| 文件流上传 | `POST https://kieai.redpandaai.co/api/file-stream-upload` | multipart，适合本地文件 |
-| URL 转存 | `POST https://kieai.redpandaai.co/api/file-url-upload` | JSON，从远程 URL 下载并转存 |
-| Base64 上传 | `POST https://kieai.redpandaai.co/api/file-base64-upload` | JSON，适合小文件 |
-
-KIE 还有 Suno、4o Image、Runway 等历史/专用 API。新的 Market 模型优先使用统一 `jobs` 契约；只有官方文档明确不走 Market 时才新增专用分支。
-
-## 2. 提交和查询
-
-### 2.1 创建任务
-
-```json
-{
-  "model": "<market-model-id>",
-  "callBackUrl": "https://your-server.example/callback",
-  "input": { "prompt": "..." }
-}
-```
-
-成功时返回 `data.taskId`。`callBackUrl` 为可选项；桌面端没有稳定公网回调地址，Henji-AI 使用轮询。
-
-### 2.2 轮询
-
-`GET https://api.kie.ai/api/v1/jobs/recordInfo?taskId=<taskId>`
-
-| 字段 | 含义 |
-|---|---|
-| `data.state` | `waiting` / `queuing` / `generating` / `success` / `fail` |
-| `data.resultJson` | 成功后的 JSON 字符串，必须再次解析 |
-| `data.failCode` / `data.failMsg` | 失败码和可见原因 |
-| `data.progress` | 部分模型返回进度 |
-| `data.creditsConsumed` | 该任务实际消耗的积分 |
-
-最常见的成功结果：
-
-```json
-{
-  "data": {
-    "state": "success",
-    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
-    "creditsConsumed": 50
-  }
-}
-```
-
-`resultJson` 不只有 `resultUrls`；个别模型返回 `images`、`videos`、`resultObject`、`firstFrameUrl` 或 `lastFrameUrl`。公共运行时已覆盖这些媒体 URL 形态，模型文档仍必须记录例外结构。
-
-## 3. 文件上传
-
-### 3.1 本地文件
-
-```bash
-curl -X POST https://kieai.redpandaai.co/api/file-stream-upload \
-  -H "Authorization: Bearer $KIE_KEY" \
-  -F "uploadPath=henji-uploads" \
-  -F "fileName=reference.png" \
-  -F "file=@/path/reference.png"
-```
-
-返回值历史上出现过两种字段，适配时兼容：
-
-- `data.fileUrl`
-- `data.downloadUrl`
-
-项目上传时不主动指定远端 `fileName`，由 KIE 生成唯一文件名，避免同名覆盖后的 CDN 缓存短暂返回旧内容。
-
-### 3.2 有效期冲突
-
-KIE 官方快速开始和页面提醒写“24 小时后删除”，文件流 OpenAPI 的描述/示例又出现“3 天”。在官方消除冲突前，项目以 **24 小时** 作为保守上限，以实际返回 `expiresAt` 为准。
-
-## 4. 获取和保存结果
-
-- `resultJson.resultUrls[]` 通常可直接下载。
-- 如果生成 URL 是 KIE 内部临时地址，可调用 `POST /api/v1/common/download-url` 换取下载链。
-- 该换链接口不接受外部 URL，传入非 KIE 文件会返回 `422`。
-- 媒体结果必须及时转存，不把供应商临时 URL 当永久资产。
-
-## 5. 计价和余额
-
-| 来源 | 用途 |
-|---|---|
-| `https://kie.ai/pricing` | 当前公开价格；按模型、模式、分辨率、时长等分行 |
-| 模型 API 文档 | 请求 schema 和模型级计费描述 |
-| `data.creditsConsumed` | 已完成任务的实际积分消耗，对账优先级最高 |
-| `GET /api/v1/chat/credit` | 当前剩余积分，返回 `{ code, msg, data }` |
-
-定价页的 `/client/v1/model-pricing/*` 是站点内部数据源，并非公开开发者稳定契约，项目不直接依赖。
-
-## 6. 项目当前实现
-
-| 能力 | 状态 | 位置 |
-|---|---|---|
-| Market 任务提交 | 已接入 | `providers/kie.ts` |
-| 统一轮询 | 已接入 | `providers/kie.ts` |
-| `resultJson` 解析 | 已接入 | `providers/kie.ts` |
-| 文件流上传 | 已接入 | `upload-providers.ts` |
-| 余额/连接检测 | 已接入 | `provider-connection.ts` |
-| 换取下载链 | 未作为通用必经步骤 | 只在结果 URL 确实不可直下时再接入 |
-
-## 7. 原始链接索引
-
-| 信息 | 链接 | 登录 |
-|---|---|---|
-| 文档总索引 | https://docs.kie.ai/llms.txt | 否 |
-| Market 统一任务查询 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
-| 文件上传快速开始 | https://docs.kie.ai/cn/file-upload-api/quickstart | 否 |
-| 文件流上传 | https://docs.kie.ai/cn/file-upload-api/upload-file-stream | 否 |
-| 获取剩余积分 | https://docs.kie.ai/cn/common-api/get-account-credits | 否 |
-| 换取生成文件下载链 | https://docs.kie.ai/cn/common-api/download-url | 否 |
-| 定价页 | https://kie.ai/pricing | 否 |
-| API Key | https://kie.ai/api-key | 是 |
+# KIE · 供应商基础文档
+
+| 项目 | 内容 |
+|---|---|
+| 最后更新 | 2026-10-13 |
+| 供应商类型 | 聚合中转（非模型原厂） |
+| 项目内 `providerId` | `kie` |
+| 生成 Base URL | `https://api.kie.ai` |
+| 上传 Base URL | `https://kieai.redpandaai.co` |
+| 鉴权 | `Authorization: Bearer <API Key>` |
+| 任务模式 | Market 模型统一异步任务 |
+| 文档/价格可见性 | 公开，无需登录；API Key 和账单需登录 |
+
+## 1. 基础端点
+
+| 用途 | 方法与路径 | 说明 |
+|---|---|---|
+| 创建 Market 任务 | `POST /api/v1/jobs/createTask` | body 为 `model` + `input`，可选 `callBackUrl` |
+| 查询 Market 任务 | `GET /api/v1/jobs/recordInfo?taskId=...` | 所有 Market 模型的统一查询入口 |
+| 查询剩余积分 | `GET /api/v1/chat/credit` | 返回 `data` 整数积分 |
+| 换取生成文件下载链 | `POST /api/v1/common/download-url` | 仅接受 KIE 生成文件 URL |
+| 文件流上传 | `POST https://kieai.redpandaai.co/api/file-stream-upload` | multipart，适合本地文件 |
+| URL 转存 | `POST https://kieai.redpandaai.co/api/file-url-upload` | JSON，从远程 URL 下载并转存 |
+| Base64 上传 | `POST https://kieai.redpandaai.co/api/file-base64-upload` | JSON，适合小文件 |
+
+KIE 还有 Suno、4o Image、Runway 等历史/专用 API。新的 Market 模型优先使用统一 `jobs` 契约；只有官方文档明确不走 Market 时才新增专用分支。
+
+## 2. 提交和查询
+
+### 2.1 创建任务
+
+```json
+{
+  "model": "<market-model-id>",
+  "callBackUrl": "https://your-server.example/callback",
+  "input": { "prompt": "..." }
+}
+```
+
+成功时返回 `data.taskId`。`callBackUrl` 为可选项；桌面端没有稳定公网回调地址，Henji-AI 使用轮询。
+
+### 2.2 轮询
+
+`GET https://api.kie.ai/api/v1/jobs/recordInfo?taskId=<taskId>`
+
+| 字段 | 含义 |
+|---|---|
+| `data.state` | `waiting` / `queuing` / `generating` / `success` / `fail` |
+| `data.resultJson` | 成功后的 JSON 字符串，必须再次解析 |
+| `data.failCode` / `data.failMsg` | 失败码和可见原因 |
+| `data.progress` | 部分模型返回进度 |
+| `data.creditsConsumed` | 该任务实际消耗的积分 |
+
+最常见的成功结果：
+
+```json
+{
+  "data": {
+    "state": "success",
+    "resultJson": "{\"resultUrls\":[\"https://...\"]}",
+    "creditsConsumed": 50
+  }
+}
+```
+
+`resultJson` 不只有 `resultUrls`；个别模型返回 `images`、`videos`、`resultObject`、`firstFrameUrl` 或 `lastFrameUrl`。公共运行时已覆盖这些媒体 URL 形态，模型文档仍必须记录例外结构。
+
+### 2.3 查询状态与错误契约（2026-10-13 核对）
+
+来源：本页索引中的官方「Market 统一任务查询」。该页明确说明业务错误时 HTTP 仍可为 200，必须检查 `code`；错误码表列出 401、422、500、501。表中没有定义 404，不将它猜为不可恢复终态。
+
+| 响应/状态 | 字段与空值契约 | SDK 行为 | 是否终止 | 副作用与资源 |
+|---|---|---|---|---|
+| `waiting` / `queuing` / `generating` | `data.state` 为字符串；处理中不要求结果 URL | 继续查询 | 否 | 不重新创建任务 |
+| `success` | `data.resultJson` 为包含结果的 JSON 字符串；有效完成仍须有媒体 URL | 返回 completed | 是 | 宿主保存结果；空结果明确拒绝 |
+| `fail` | `data.failCode` / `data.failMsg` 描述任务失败 | 返回供应商任务错误 | 是 | 不自动重放提交 |
+| 业务 `401` | 官方定义 API Key 无效或缺失；`msg` 保留供应商原因 | authentication，`retryable:false` | 是 | 一次查询后停止，提示检查 Key |
+| HTTP `401` / `403`，或收到的业务 `403` | HTTP 鉴权/权限失败；业务 403 是本项目保护分支，官方查询错误表未列出 | authentication，`retryable:false`，带 status/providerCode/providerMessage | 是 | 不自动重试；不是余额错误 |
+| 业务 `422` | 官方定义缺少 taskId、任务不存在或不属于账号 | 保留 code/msg 的查询错误；本次不改变原有有界重试策略 | 连续失败达上限时 | 不把查询失败当作任务仍在运行 |
+| 业务 `500` / `501` 及未知非 200 code（如 404） | 官方分别定义内部错误/生成失败；404 终态语义未说明 | 保留 code/msg，按查询失败有界重试 | 连续 20 次失败时 | 最后错误包含供应商原因；成功查询重置计数 |
+
+官方未说明查询乱序、重复响应和 404 恢复语义。SDK 按顺序一次一查；取消会停止查询并释放等待计时器，不等同于服务端撤销已创建任务。
+
+## 3. 文件上传
+
+### 3.1 本地文件
+
+```bash
+curl -X POST https://kieai.redpandaai.co/api/file-stream-upload \
+  -H "Authorization: Bearer $KIE_KEY" \
+  -F "uploadPath=henji-uploads" \
+  -F "fileName=reference.png" \
+  -F "file=@/path/reference.png"
+```
+
+返回值历史上出现过两种字段，适配时兼容：
+
+- `data.fileUrl`
+- `data.downloadUrl`
+
+项目上传时不主动指定远端 `fileName`，由 KIE 生成唯一文件名，避免同名覆盖后的 CDN 缓存短暂返回旧内容。
+
+本地文件与 data URI 都先经此端点换取公网 URL。没有 KIE Key 明确返回 `missing_api_key`；上传失败保留原错误并记录 `ai_runtime.upload.kie_failed`，不再退回 data URI 后提交生成。日志使用实际请求的 providerId，兼容入口的 ModelScope 请求不误标为 KIE。
+
+| 上传阶段 | 字段契约/来源 | SDK 结果 | 资源释放 |
+|---|---|---|---|
+| 开始 | 官方 multipart：file、uploadPath；日志仅 route/mimeType/bytes | `kie_started` | 不记录文件内容或凭据 |
+| 成功 | 官方示例返回 `success:true, code:200, data.downloadUrl`；另保留既有 fileUrl 形态 | 公网 URL + `kie_completed` | 清理期限计时器与父信号监听 |
+| HTTP/网络错误、缺少 URL | 负例以 synthetic-negative 标记；不得冒充官方字面响应 | 原错误 + `kie_failed`；停止预处理 | 同上 |
+| 用户取消 | 本项目 AbortSignal 契约，官方未说明服务端取消上传规则 | `cancelled` + `kie_cancelled`；不转成上传失败、不回退 data URI | 中止 fetch/重试等待并清理监听 |
+| 上传超过 120 秒 | 本项目客户端期限，复用 Fal 的期限机制，并非供应商 SLA | `upload_timeout` + `kie_failed` | 同上 |
+
+网络侧使用联动的期限子信号，用户信号中止会立即传递；同一次上传的网络请求及预连接重试共用该信号。取消不能保证删除服务端已收取的部分文件。
+
+### 3.2 有效期冲突
+
+KIE 官方快速开始和页面提醒写“24 小时后删除”，文件流 OpenAPI 的描述/示例又出现“3 天”。在官方消除冲突前，项目以 **24 小时** 作为保守上限，以实际返回 `expiresAt` 为准。
+
+## 4. 获取和保存结果
+
+- `resultJson.resultUrls[]` 通常可直接下载。
+- 如果生成 URL 是 KIE 内部临时地址，可调用 `POST /api/v1/common/download-url` 换取下载链。
+- 该换链接口不接受外部 URL，传入非 KIE 文件会返回 `422`。
+- 媒体结果必须及时转存，不把供应商临时 URL 当永久资产。
+
+## 5. 计价和余额
+
+| 来源 | 用途 |
+|---|---|
+| `https://kie.ai/pricing` | 当前公开价格；按模型、模式、分辨率、时长等分行 |
+| 模型 API 文档 | 请求 schema 和模型级计费描述 |
+| `data.creditsConsumed` | 已完成任务的实际积分消耗，对账优先级最高 |
+| `GET /api/v1/chat/credit` | 当前剩余积分，返回 `{ code, msg, data }` |
+
+定价页的 `/client/v1/model-pricing/*` 是站点内部数据源，并非公开开发者稳定契约，项目不直接依赖。
+
+## 6. 项目当前实现
+
+| 能力 | 状态 | 位置 |
+|---|---|---|
+| Market 任务提交 | 已接入 | `providers/kie.ts` |
+| 统一轮询 | 已接入 | `providers/kie.ts` |
+| `resultJson` 解析 | 已接入 | `providers/kie.ts` |
+| 文件流上传 | 已接入 | `upload-providers.ts` |
+| 余额/连接检测 | 已接入 | `provider-connection.ts` |
+| 换取下载链 | 未作为通用必经步骤 | 只在结果 URL 确实不可直下时再接入 |
+
+## 7. 原始链接索引
+
+| 信息 | 链接 | 登录 |
+|---|---|---|
+| 文档总索引 | https://docs.kie.ai/llms.txt | 否 |
+| Market 统一任务查询 | https://docs.kie.ai/cn/market/common/get-task-detail | 否 |
+| 文件上传快速开始 | https://docs.kie.ai/cn/file-upload-api/quickstart | 否 |
+| 文件流上传 | https://docs.kie.ai/cn/file-upload-api/upload-file-stream | 否 |
+| 获取剩余积分 | https://docs.kie.ai/cn/common-api/get-account-credits | 否 |
+| 换取生成文件下载链 | https://docs.kie.ai/cn/common-api/download-url | 否 |
+| 定价页 | https://kie.ai/pricing | 否 |
+| API Key | https://kie.ai/api-key | 是 |

package/docs/model-adaptation//344/276/233/345/272/224/345/225/206//345/200/231/351/200/211/344/276/233/345/272/224/345/225/206/350/260/203/347/240/224-/345/233/276/347/211/207/345/267/245/345/205/267.md

@@ -1,151 +1,151 @@
-# 图片工具候选供应商调研
-
-> 状态：调研完成，尚未适配
-> 核验日期：2026-08-29
-> 范围：高清放大、重打光、图片视角变化、扩图、照片修复、背景移除，以及图片/视频/音频生成、价格优惠和中国内地访问条件。
-
-## 结论
-
-推荐顺序：
-
-1. **Segmind（P0）**：目标图片工具覆盖最完整，异步协议统一，适合先做完整 provider。
-2. **WaveSpeedAI（P0）**：模型池最大、公开折扣最明显，多角度/放大/重打光/修复/抠图均有明确独立入口。
-3. **PiAPI（P1）**：放大、抠图、扩图价格低，提供简体中文站和 USDT 优惠，适合作为低价补充。
-4. **Replicate（P2）**：长尾能力强，但社区模型版本、许可证、下架风险和结果落盘时限需要额外治理。
-5. **Novita AI（P3）**：多模态齐全，但当前没有足够独立图片工具覆盖，本轮暂缓。
-
-公开资料不足以把任何一家写成“已确认中国内地友好”。正式选型前必须从中国移动、联通、电信网络分别测试 API 域名和结果媒体域名；DNS/TLS/未鉴权请求可先做零费用探测，付费生成另行授权。
-
-## 能力矩阵
-
-| 供应商 | 高清放大 | 重打光 | 图片视角 | 背景移除 | 图片扩图 | 照片修复 | 图片生成 | 视频生成 | 音频生成 |
-|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
-| Segmind | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| WaveSpeedAI | ✅ | ✅ | ✅ | ✅ | 待确认独立图片端点 | ✅ | ✅ | ✅ | ✅ |
-| PiAPI | ✅ | 未发现 | 未发现 | ✅ | ✅ | 未发现 | ✅ | ✅ | ✅ |
-| Replicate | ✅ | 社区模型 | 社区模型 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Novita AI | 生成参数内置 | 未发现 | 未发现 | 未发现 | 未发现 | 人脸修复开关 | ✅ | ✅ | ✅ |
-
-## 1. Segmind（P0）
-
-### 已核验能力
-
-- 多角度：[Qwen Image Edit Plus Multiple Angles](https://www.segmind.com/models/qwen-image-edit-plus-multiple-angle)，支持镜头移动、旋转和远近控制。
-- 重打光：[Segmind Relighting V2](https://www.segmind.com/models/segmind-relighting-v2)，支持方向、类型、颜色和强度控制。
-- 高清放大：[Bria Increase Resolution](https://www.segmind.com/models/bria-increase-resolution)，支持 2×/4× 与 Alpha。
-- 扩图：[Flux Fill Pro](https://www.segmind.com/models/flux-fill-pro)。
-- 背景移除：[Bria RMBG 2.0](https://www.segmind.com/models/bria-remove-background)。
-- 照片修复：[SUPIR](https://www.segmind.com/models/supir)。
-- 另有独立的[视频模型目录](https://www.segmind.com/models/all/best-video-models)和[音频模型目录](https://www.segmind.com/models/all/text-to-speech-models)。
-
-### 公共协议
-
-- Base URL：`https://api.segmind.com`
-- 鉴权：`x-api-key`，见[官方鉴权文档](https://docs.segmind.com/docs/get-started/authentication)。
-- 同步：`POST /v1/{model-slug}`。
-- 异步：`POST /v2/{model-slug}`；提交返回 `request_id`、`status_url`、`response_url`。
-- 查询：`GET /v2/requests/{id}/status`、`GET /v2/requests/{id}`。
-- 终态：`COMPLETED` / `FAILED`。多角度请求形状见其[官方 API 页面](https://www.segmind.com/models/qwen-image-edit-plus-multiple-angle/api)。
-
-### 价格、优惠与内地访问
-
-- [官方价格页](https://www.segmind.com/pricing)明确提供 volume discounts，并写有“The more you buy, the more you save”。
-- 公开计划存在月付积分溢价和企业年付折扣；最终适配必须按模型页实时价格逐项记录。
-- 未发现中国内地节点、备案域名、本地支付或网络 SLA；示例媒体依赖云存储域名，访问结论为**未知、待实测**。
-
-### 建议首批
-
-多角度、Relighting V2、Bria Increase Resolution、Flux Fill Pro、Bria RMBG 2.0、SUPIR。v2 公共轮询层只实现一次，各模型保持独立 schema。
-
-## 2. WaveSpeedAI（P0）
-
-### 已核验能力
-
-- 多角度：[Qwen Image Edit Multiple Angles](https://wavespeed.ai/models/wavespeed-ai/qwen-image/edit-multiple-angles)。
-- 重打光：[Bria Fibo Relight](https://wavespeed.ai/models/bria/fibo/relight)。
-- 高清放大：[Clarity Pro Upscaler](https://wavespeed.ai/models/clarity-ai/pro-upscaler)、[WaveSpeed Image Upscaler](https://wavespeed.ai/models/wavespeed-ai/image-upscaler)。
-- 背景移除：[WaveSpeed Background Remover](https://wavespeed.ai/models/wavespeed-ai/image-background-remover)。
-- 照片修复：[Bria Fibo Restore](https://wavespeed.ai/models/bria/fibo/restore)。
-- 官方目录已发现视频扩图，但尚未核到明确的独立**图片** outpaint endpoint，因此不得用泛化编辑能力替代确认。
-
-### 公共协议
-
-- Base URL：`https://api.wavespeed.ai/api/v3`
-- 鉴权：`Authorization: Bearer ...`，见[鉴权文档](https://wavespeed.ai/docs/api-authentication)。
-- 提交：`POST /api/v3/{model_id}`，见[提交文档](https://wavespeed.ai/docs/submit-task)。
-- 查询：`GET /api/v3/predictions/{task-id}/result`，见[结果查询](https://wavespeed.ai/docs/get-result)。
-- 终态：`completed`；失败类终态包括 `failed`、`cancelled`、`timeout`、`deleted`。
-- 支持 webhook，部分模型支持同步模式。
-
-### 价格、优惠与内地访问
-
-- 官方模型目录直接展示 5%–50% OFF，且[价格页](https://wavespeed.ai/pricing)提供企业 volume discounts。
-- 官网提供中文版本提示，但未发现中国节点、内地 API SLA 或支付宝/微信支付证据；访问结论仍为**未知、待实测**。
-
-### 建议首批
-
-多角度、Fibo Relight、Image Upscaler、Background Remover、Fibo Restore；图片 Outpaint 等官方确认独立端点后再加入。
-
-## 3. PiAPI（P1）
-
-### 已核验能力
-
-- 高清放大：[Super Resolution API](https://piapi.ai/docs/image-editing-api/super-resolution-api)，支持 2/4/8×与人脸增强。
-- 背景移除：[Remove Background API](https://piapi.ai/docs/image-editing-api/remove-background-api)，支持 RMBG-1.4、RMBG-2.0、BEN2。
-- 扩图：[Flux Outpaint](https://piapi.ai/docs/flux-redux-fill-variation-inpaint-outpaint)。
-- 当前官方文档索引未发现独立重打光、照片修复或图片多角度；[WanX Camera Control](https://piapi.ai/docs/wanx-api/camera-control.md)是视频镜头控制，不能计入图片视角能力。
-
-### 公共协议
-
-- Base URL：`https://api.piapi.ai`
-- 鉴权：`x-api-key`
-- 统一提交：`POST /api/v1/task`
-- 统一查询：`GET /api/v1/task/{task_id}`
-- 请求主体统一为 `model`、`task_type`、`input`，支持 webhook。见[Quickstart](https://piapi.ai/docs/quickstart)和[统一 API schema](https://piapi.ai/docs/unified-api-schema)。
-
-### 价格、优惠与内地访问
-
-- 放大和背景移除页面公开价均很低；落地前仍需按实际输出 MP 与任务返回账单校对。
-- [Benefits](https://piapi.ai/benefits)公开 USDT 大额充值 5%/8%/11%/15% 赠送档位，部分模型另有活动折扣。
-- 有[简体中文站](https://piapi.ai/zh-CN)且支持 USDT，支付可达性线索最好；但没有中国备用 API 域名、内地节点或 SLA，网络访问仍需实测。
-
-## 4. Replicate（P2）
-
-### 已核验能力
-
-- 高清放大：[Recraft Crisp Upscale](https://replicate.com/recraft-ai/recraft-crisp-upscale)、[Google Upscaler](https://replicate.com/google/upscaler)。
-- 重打光：[IC-Light Background](https://replicate.com/zsxkib/ic-light-background)（社区模型）。
-- 多视角：[Zero123++](https://replicate.com/jd7h/zero123plusplus)（社区模型）。
-- 背景移除：[Bria Remove Background](https://replicate.com/bria/remove-background)。
-- 扩图：[FLUX Fill Pro](https://replicate.com/black-forest-labs/flux-fill-pro)。
-- 照片修复：[Microsoft Old Photos](https://replicate.com/microsoft/bringing-old-photos-back-to-life)。
-- 图片、视频、音频均有大规模目录，例如 [Seedance 2.0](https://replicate.com/bytedance/seedance-2.0) 与 [Stable Audio 2.5](https://replicate.com/stability-ai/stable-audio-2.5)。
-
-### 公共协议与风险
-
-- Base URL：`https://api.replicate.com/v1`，Bearer 鉴权。
-- 官方模型：`POST /v1/models/{owner}/{name}/predictions`；社区模型：`POST /v1/predictions` 并固定 version hash。
-- 查询：`GET /v1/predictions/{id}`；状态为 `starting`、`processing`、`succeeded`、`failed`、`canceled`。见[HTTP API](https://replicate.com/docs/reference/http)和[预测说明](https://replicate.com/docs/topics/predictions/create-a-prediction)。
-- 预测输入、输出和日志默认在一小时后清理；结果域名 `replicate.delivery` / `*.replicate.delivery` 必须纳入媒体下载白名单并及时落盘。
-- 社区模型必须锁定 version、审计许可证并处理作者更新/下架，不应首版开放任意 owner。
-
-### 价格与内地访问
-
-- [价格页](https://replicate.com/pricing)按输出或 GPU 秒计费，[企业方案](https://replicate.com/enterprise)提供 volume discounts，个别模型有临时折扣。
-- 无中文站、中国节点或内地 SLA；API 与结果媒体域名都需要实测。
-
-## 5. Novita AI（P3）
-
-- 官方 [llms.txt](https://novita.ai/llms.txt)显示其覆盖图片、视频、音频和 LLM。
-- Base URL：`https://api.novita.ai`，Bearer 鉴权；v3 异步任务通过 [`GET /v3/async/task-result`](https://novita.ai/docs/api-reference/model-apis-task-result)统一查询。
-- 统一状态包括 `TASK_STATUS_QUEUED/PROCESSING/SUCCEED/FAILED`，结果可包含 images/videos/audios。
-- 当前目录未核到独立 relight、图片视角、背景移除、outpaint 或完整照片修复 endpoint；[V2→V3 迁移文档](https://novita.ai/docs/guides/model-apis-v2-to-v3-migration)中的 `hires_fix.upscaler`、`restore_faces` 只是生成参数，不等于独立图片工具。
-- 媒体图片工具未核到稳定折扣，中国内地访问条件同样未知。因此本轮暂缓。
-
-## 适配前置验证清单
-
-1. 从中国移动、联通、电信分别测试主 API 域名的 DNS、TLS、首包时间与失败率。
-2. 同时测试上传域名和结果媒体域名；只测官网不能代表生成链路可用。
-3. 用不产生模型费用的鉴权失败/模型列表请求先验证网络和错误结构。
-4. 获得付费授权后，每家只选择 1 个低价工具做提交、轮询、取消、失败、落盘和实扣金额验证。
-5. 按真实结果再决定 Segmind 与 WaveSpeedAI 的先后顺序；PiAPI 作为价格/支付补充，不替代多角度和重打光主供应商。
+# 图片工具候选供应商调研
+
+> 状态：调研完成，尚未适配
+> 核验日期：2026-08-29
+> 范围：高清放大、重打光、图片视角变化、扩图、照片修复、背景移除，以及图片/视频/音频生成、价格优惠和中国内地访问条件。
+
+## 结论
+
+推荐顺序：
+
+1. **Segmind（P0）**：目标图片工具覆盖最完整，异步协议统一，适合先做完整 provider。
+2. **WaveSpeedAI（P0）**：模型池最大、公开折扣最明显，多角度/放大/重打光/修复/抠图均有明确独立入口。
+3. **PiAPI（P1）**：放大、抠图、扩图价格低，提供简体中文站和 USDT 优惠，适合作为低价补充。
+4. **Replicate（P2）**：长尾能力强，但社区模型版本、许可证、下架风险和结果落盘时限需要额外治理。
+5. **Novita AI（P3）**：多模态齐全，但当前没有足够独立图片工具覆盖，本轮暂缓。
+
+公开资料不足以把任何一家写成“已确认中国内地友好”。正式选型前必须从中国移动、联通、电信网络分别测试 API 域名和结果媒体域名；DNS/TLS/未鉴权请求可先做零费用探测，付费生成另行授权。
+
+## 能力矩阵
+
+| 供应商 | 高清放大 | 重打光 | 图片视角 | 背景移除 | 图片扩图 | 照片修复 | 图片生成 | 视频生成 | 音频生成 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| Segmind | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| WaveSpeedAI | ✅ | ✅ | ✅ | ✅ | 待确认独立图片端点 | ✅ | ✅ | ✅ | ✅ |
+| PiAPI | ✅ | 未发现 | 未发现 | ✅ | ✅ | 未发现 | ✅ | ✅ | ✅ |
+| Replicate | ✅ | 社区模型 | 社区模型 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Novita AI | 生成参数内置 | 未发现 | 未发现 | 未发现 | 未发现 | 人脸修复开关 | ✅ | ✅ | ✅ |
+
+## 1. Segmind（P0）
+
+### 已核验能力
+
+- 多角度：[Qwen Image Edit Plus Multiple Angles](https://www.segmind.com/models/qwen-image-edit-plus-multiple-angle)，支持镜头移动、旋转和远近控制。
+- 重打光：[Segmind Relighting V2](https://www.segmind.com/models/segmind-relighting-v2)，支持方向、类型、颜色和强度控制。
+- 高清放大：[Bria Increase Resolution](https://www.segmind.com/models/bria-increase-resolution)，支持 2×/4× 与 Alpha。
+- 扩图：[Flux Fill Pro](https://www.segmind.com/models/flux-fill-pro)。
+- 背景移除：[Bria RMBG 2.0](https://www.segmind.com/models/bria-remove-background)。
+- 照片修复：[SUPIR](https://www.segmind.com/models/supir)。
+- 另有独立的[视频模型目录](https://www.segmind.com/models/all/best-video-models)和[音频模型目录](https://www.segmind.com/models/all/text-to-speech-models)。
+
+### 公共协议
+
+- Base URL：`https://api.segmind.com`
+- 鉴权：`x-api-key`，见[官方鉴权文档](https://docs.segmind.com/docs/get-started/authentication)。
+- 同步：`POST /v1/{model-slug}`。
+- 异步：`POST /v2/{model-slug}`；提交返回 `request_id`、`status_url`、`response_url`。
+- 查询：`GET /v2/requests/{id}/status`、`GET /v2/requests/{id}`。
+- 终态：`COMPLETED` / `FAILED`。多角度请求形状见其[官方 API 页面](https://www.segmind.com/models/qwen-image-edit-plus-multiple-angle/api)。
+
+### 价格、优惠与内地访问
+
+- [官方价格页](https://www.segmind.com/pricing)明确提供 volume discounts，并写有“The more you buy, the more you save”。
+- 公开计划存在月付积分溢价和企业年付折扣；最终适配必须按模型页实时价格逐项记录。
+- 未发现中国内地节点、备案域名、本地支付或网络 SLA；示例媒体依赖云存储域名，访问结论为**未知、待实测**。
+
+### 建议首批
+
+多角度、Relighting V2、Bria Increase Resolution、Flux Fill Pro、Bria RMBG 2.0、SUPIR。v2 公共轮询层只实现一次，各模型保持独立 schema。
+
+## 2. WaveSpeedAI（P0）
+
+### 已核验能力
+
+- 多角度：[Qwen Image Edit Multiple Angles](https://wavespeed.ai/models/wavespeed-ai/qwen-image/edit-multiple-angles)。
+- 重打光：[Bria Fibo Relight](https://wavespeed.ai/models/bria/fibo/relight)。
+- 高清放大：[Clarity Pro Upscaler](https://wavespeed.ai/models/clarity-ai/pro-upscaler)、[WaveSpeed Image Upscaler](https://wavespeed.ai/models/wavespeed-ai/image-upscaler)。
+- 背景移除：[WaveSpeed Background Remover](https://wavespeed.ai/models/wavespeed-ai/image-background-remover)。
+- 照片修复：[Bria Fibo Restore](https://wavespeed.ai/models/bria/fibo/restore)。
+- 官方目录已发现视频扩图，但尚未核到明确的独立**图片** outpaint endpoint，因此不得用泛化编辑能力替代确认。
+
+### 公共协议
+
+- Base URL：`https://api.wavespeed.ai/api/v3`
+- 鉴权：`Authorization: Bearer ...`，见[鉴权文档](https://wavespeed.ai/docs/api-authentication)。
+- 提交：`POST /api/v3/{model_id}`，见[提交文档](https://wavespeed.ai/docs/submit-task)。
+- 查询：`GET /api/v3/predictions/{task-id}/result`，见[结果查询](https://wavespeed.ai/docs/get-result)。
+- 终态：`completed`；失败类终态包括 `failed`、`cancelled`、`timeout`、`deleted`。
+- 支持 webhook，部分模型支持同步模式。
+
+### 价格、优惠与内地访问
+
+- 官方模型目录直接展示 5%–50% OFF，且[价格页](https://wavespeed.ai/pricing)提供企业 volume discounts。
+- 官网提供中文版本提示，但未发现中国节点、内地 API SLA 或支付宝/微信支付证据；访问结论仍为**未知、待实测**。
+
+### 建议首批
+
+多角度、Fibo Relight、Image Upscaler、Background Remover、Fibo Restore；图片 Outpaint 等官方确认独立端点后再加入。
+
+## 3. PiAPI（P1）
+
+### 已核验能力
+
+- 高清放大：[Super Resolution API](https://piapi.ai/docs/image-editing-api/super-resolution-api)，支持 2/4/8×与人脸增强。
+- 背景移除：[Remove Background API](https://piapi.ai/docs/image-editing-api/remove-background-api)，支持 RMBG-1.4、RMBG-2.0、BEN2。
+- 扩图：[Flux Outpaint](https://piapi.ai/docs/flux-redux-fill-variation-inpaint-outpaint)。
+- 当前官方文档索引未发现独立重打光、照片修复或图片多角度；[WanX Camera Control](https://piapi.ai/docs/wanx-api/camera-control.md)是视频镜头控制，不能计入图片视角能力。
+
+### 公共协议
+
+- Base URL：`https://api.piapi.ai`
+- 鉴权：`x-api-key`
+- 统一提交：`POST /api/v1/task`
+- 统一查询：`GET /api/v1/task/{task_id}`
+- 请求主体统一为 `model`、`task_type`、`input`，支持 webhook。见[Quickstart](https://piapi.ai/docs/quickstart)和[统一 API schema](https://piapi.ai/docs/unified-api-schema)。
+
+### 价格、优惠与内地访问
+
+- 放大和背景移除页面公开价均很低；落地前仍需按实际输出 MP 与任务返回账单校对。
+- [Benefits](https://piapi.ai/benefits)公开 USDT 大额充值 5%/8%/11%/15% 赠送档位，部分模型另有活动折扣。
+- 有[简体中文站](https://piapi.ai/zh-CN)且支持 USDT，支付可达性线索最好；但没有中国备用 API 域名、内地节点或 SLA，网络访问仍需实测。
+
+## 4. Replicate（P2）
+
+### 已核验能力
+
+- 高清放大：[Recraft Crisp Upscale](https://replicate.com/recraft-ai/recraft-crisp-upscale)、[Google Upscaler](https://replicate.com/google/upscaler)。
+- 重打光：[IC-Light Background](https://replicate.com/zsxkib/ic-light-background)（社区模型）。
+- 多视角：[Zero123++](https://replicate.com/jd7h/zero123plusplus)（社区模型）。
+- 背景移除：[Bria Remove Background](https://replicate.com/bria/remove-background)。
+- 扩图：[FLUX Fill Pro](https://replicate.com/black-forest-labs/flux-fill-pro)。
+- 照片修复：[Microsoft Old Photos](https://replicate.com/microsoft/bringing-old-photos-back-to-life)。
+- 图片、视频、音频均有大规模目录，例如 [Seedance 2.0](https://replicate.com/bytedance/seedance-2.0) 与 [Stable Audio 2.5](https://replicate.com/stability-ai/stable-audio-2.5)。
+
+### 公共协议与风险
+
+- Base URL：`https://api.replicate.com/v1`，Bearer 鉴权。
+- 官方模型：`POST /v1/models/{owner}/{name}/predictions`；社区模型：`POST /v1/predictions` 并固定 version hash。
+- 查询：`GET /v1/predictions/{id}`；状态为 `starting`、`processing`、`succeeded`、`failed`、`canceled`。见[HTTP API](https://replicate.com/docs/reference/http)和[预测说明](https://replicate.com/docs/topics/predictions/create-a-prediction)。
+- 预测输入、输出和日志默认在一小时后清理；结果域名 `replicate.delivery` / `*.replicate.delivery` 必须纳入媒体下载白名单并及时落盘。
+- 社区模型必须锁定 version、审计许可证并处理作者更新/下架，不应首版开放任意 owner。
+
+### 价格与内地访问
+
+- [价格页](https://replicate.com/pricing)按输出或 GPU 秒计费，[企业方案](https://replicate.com/enterprise)提供 volume discounts，个别模型有临时折扣。
+- 无中文站、中国节点或内地 SLA；API 与结果媒体域名都需要实测。
+
+## 5. Novita AI（P3）
+
+- 官方 [llms.txt](https://novita.ai/llms.txt)显示其覆盖图片、视频、音频和 LLM。
+- Base URL：`https://api.novita.ai`，Bearer 鉴权；v3 异步任务通过 [`GET /v3/async/task-result`](https://novita.ai/docs/api-reference/model-apis-task-result)统一查询。
+- 统一状态包括 `TASK_STATUS_QUEUED/PROCESSING/SUCCEED/FAILED`，结果可包含 images/videos/audios。
+- 当前目录未核到独立 relight、图片视角、背景移除、outpaint 或完整照片修复 endpoint；[V2→V3 迁移文档](https://novita.ai/docs/guides/model-apis-v2-to-v3-migration)中的 `hires_fix.upscaler`、`restore_faces` 只是生成参数，不等于独立图片工具。
+- 媒体图片工具未核到稳定折扣，中国内地访问条件同样未知。因此本轮暂缓。
+
+## 适配前置验证清单
+
+1. 从中国移动、联通、电信分别测试主 API 域名的 DNS、TLS、首包时间与失败率。
+2. 同时测试上传域名和结果媒体域名；只测官网不能代表生成链路可用。
+3. 用不产生模型费用的鉴权失败/模型列表请求先验证网络和错误结构。
+4. 获得付费授权后，每家只选择 1 个低价工具做提交、轮询、取消、失败、落盘和实扣金额验证。
+5. 按真实结果再决定 Segmind 与 WaveSpeedAI 的先后顺序；PiAPI 作为价格/支付补充，不替代多角度和重打光主供应商。