---
url: /docs/agentbuff-stack/image-to-svg-contract.md
---
# 图片转矢量：候选接口与接入核对

核对日期：2026-10-11，北京时间；源码基线 `2642fd42`。本页是 I7 的接入准备，**未实现或启用图片转 SVG，也未调用收费接口**。首个真实任务仍待用户选择；现有文本规范化演示继续使用原处理器。接口可用与有报价不证明搜索需求、付费用户或订阅成立。

## 为什么保留这个候选

如果第一站沿用此前讨论的 Image to SVG，其交付应为上传图片 → 矢量化 → 对照预览 → 下载可编辑 SVG。Recraft 有直接转换接口，适合继续验证单一任务；能否保留细节、文字与可编辑路径仍需真实样本。文字提示生成一幅新的 SVG 使用另一接口，不能当成保留原图的转换质量证据。[官方转换说明](https://www.recraft.ai/docs/api-reference/tools/vectorize)

## 已核对的外部契约

| 项目 | 当前公开资料 | 对接选择 / 尚缺证据 |
| --- | --- | --- |
| 请求 | `POST https://external.api.recraft.ai/v1/images/vectorize`，服务端 Bearer 认证 | 使用 Worker 原生 HTTP，不为一个操作新增模型路由器或客户端 SDK。[接口说明](https://www.recraft.ai/docs/api-reference/tools/vectorize) |
| 输入 | PNG / JPEG / WebP，低于 20 MB；短边至少 256、长边不超过 4096 像素，最多 16 MP | 模板先保持已有 PNG / JPEG 与 5 MiB 限制；新增像素尺寸检查，不宣称已有 WebP 支持。[限制说明](https://www.recraft.ai/docs/api-reference/appendix) |
| 传送方式 | JSON 可传图片 URL 或数据 URL，也支持二进制表单 | 首轮采用 JSON 数据 URL，从私有 R2 读取原始字节后提交；不公开私有输入对象。[输入说明](https://www.recraft.ai/docs/api-reference/image-inputs-and-results) |
| 响应格式 | 可以返回链接、Base64 或多段字节 | 首轮选择 Base64，限制响应与解码大小后存入原私有结果链路；不把外部链接交给用户作为永久结果。[结果说明](https://www.recraft.ai/docs/api-reference/image-inputs-and-results) |
| 成功对象 | 单个 `image`，含 `image_id`；顶层有 `created` 与 `credits` | 与生成图片的数组响应不同；图片编号不是可查询的请求编号，不混用。[转换响应](https://www.recraft.ai/docs/api-reference/tools/vectorize) |
| 结果链接 | 公开、无需登录，约 24 小时；链接丢失不能恢复 | 不用链接模式替代本站所有权校验及存储保留策略。[保存限制](https://www.recraft.ai/docs/api-reference/appendix) |
| 限额 | 每个供应商用户每分钟 100 图片、每秒 5 请求；所有令牌共享 | 本站用户限流不能证明供应商账号总量受限，真实环境需验证总预算 / 并发。[限额说明](https://www.recraft.ai/docs/api-reference/appendix) |

以上是官方公开契约，不是实测结果。输出为 SVG 的声明不能证明内容全是矢量路径，也不能证明复杂照片、文字、渐变或切割用途的质量。

## 规格中发现的三个接入边界

直接下载并解析官方 JSON OpenAPI：61,391 字节，SHA-256 为 `06ca4897b0eb27435f370c2242813a748e52ff28f843a3859a46d44f1e23fba4`。确认转换操作、响应引用和结果格式后，按完整路径与字符串检索：本次规格没有记录幂等参数，也没有公开转换任务的查询 / 取消 / 结果找回操作。这个结论只覆盖本次公开规格，不能推断供应商内部没有相关能力。[官方规格](https://www.recraft.ai/docs/api-reference/openapi.json)

第一，文档表单示例使用 `file`，本次 OpenAPI 的二进制请求却继承名为 `image` 的字段；两者不一致。JSON 的图片字段在两份资料一致，因此首轮选择数据 URL。不要照搬表单示例并假称已确认运行。[表单说明](https://www.recraft.ai/docs/api-reference/tools/vectorize)、[官方规格](https://www.recraft.ai/docs/api-reference/openapi.json)

第二，转换操作没有可指定的模型版本字段，响应也没有模型版本。规格顶部的 `0.0.1` 是 API 文档版本；本站处理器版本也只能表示自己的代码契约。供应商算法版本保持未知，不能填成 V4.1，也不能宣称锁定了不可变模型。是否能满足本站对固定版本的要求，需供应商确认或另选具备版本证据的服务。[官方规格](https://www.recraft.ai/docs/api-reference/openapi.json)

第三，官方错误说明建议对网络超时与服务错误退避重试，但未承诺重试免费或收费去重。本项目要求不确定调用进入 `reconciling`：付费请求已可能到达供应商而响应丢失时，保持待核对，不直接补发。收到成功结果而本站落库失败，也必须与重新调用供应商分开恢复；这属于本项目交付规则。[官方错误说明](https://www.recraft.ai/docs/api-reference/error-handling)

## 成本怎样记录

当前公开价格为每次转换 10 个 API 单位，即 0.01 美元；单位包换算为 1 美元 / 1000 单位。按此报价，100 次为 1 美元，1000 次为 10 美元；这是报价推算，仅包含转换，不是实际账单，也不包含存储、失败、不确定重复、支付费用或其他处理。[官方价格](https://www.recraft.ai/docs/api-reference/pricing)

真实接入时分别保存供应商实际返回的单位数、报价版本 / 日期、估算金额与货币，以及本站用户的积分报价和扣返结果。只有报价而没有请求响应时，实际用量与已核实费用留空；供应商已收费但结果不合格导致用户积分返还，也不能把供应商成本清零。若要对照余额，需隔离其他同账号请求；总余额差不能直接归因给某次任务。

## 现有代码需要怎样扩展

以下按当前源码核对，不是已完成改造。继续复用同一任务、账本、私有存储和维护入口。

| 入口 | 当前限制 | 接入时需要的具体改动 |
| --- | --- | --- |
| `tasks/store.ts` 与 `db/schema/tasks.ts` | 提交只接受文本处理器；参数类型与输入 pin 都按文本设置 | 增加一个明确的图片处理器与严格参数分支；按处理器校验输入，原文本请求摘要与重放保持 |
| `tasks/consumer.ts` | 只执行文本规范化 | 先核对输入哈希、尺寸和预算，再记录执行边界；一次外部请求之后的存储故障不重新请求供应商 |
| `tasks/lifecycle.ts` 与 `tasks/rules.ts` | 未知处理器过期进入待核对；仅文本可自动重试 | 为已收到结果 / 已知拒绝 / 不确定发送分别定义恢复，不把存储重试复用为付费调用重试；取消不能伪称供应商已停止 |
| 任务执行记录 | 没有供应商编号、单位数、版本或费用字段 | 在新的增量迁移中记录实际已知事实、空值和调用状态，原 SQL 历史保持；不会给旧文本任务补造零成本 |
| `tasks/results.ts` 与文件校验 | 结果固定命名为文本；上传允许四种已有类型 | 增加服务端 SVG 结果契约、结构 / 大小 / 内容检查和文件类型；不因此默认允许用户上传任意 SVG |
| 文件预览与下载 | 图片用 Blob 图片预览，私有读取有 CSP；文本任务页面文案固定 | 增加原图 / 结果对照及可理解的限制；SVG 不作为 HTML 插入；保留跨账号隔离、下载和到期清理 |

SVG 验收需要解析真实结构并检查视口、路径与资源引用；拒绝脚本、外部依赖、嵌入位图冒充矢量以及超限输出。受限图片预览和下载还需实际浏览器复验，不能仅依靠字符串含有 SVG 标签。颜色 / 路径复杂度与文字保真属于质量样本，结构合格不自动等于产品可用。

## 下一次真实验收

任务选定且测试调用范围明确后，使用自有或有许可的固定输入：简单图标、透明图案、带文字标识、渐变插画、复杂照片，以及尺寸 / 类型边界。每份记录输入和输出摘要、像素尺寸、路径 / 嵌入对象、耗时、供应商编号 / 单位、人工质量判定及费用来源；不先填写成功率或“一天能做完”。

本地受控流程需覆盖关闭 / 缺配置、明确拒绝、限流、坏输出、发送后超时、成功结果持久化中断、重复队列、取消和积分返还。真实小批次再确认格式契约、转换质量、实际费用与 Worker 限制；两类证据分别保存。正常主库保持已授权的 0012，新增模式只在对应独立环境验收。

本轮仅获取公开文档与规格，本机缓存位于忽略的 `.local/recraft-contract-2026-10-11/`。Cloudflare 登录复查仍为未登录；没有新增未使用的模型密钥字段、执行迁移、发送图片、调用模型或部署。I7、I15 云端及 I16 两个真实产品继续未完成。