API 图像生成到交付的完整链路

API 图像生成到交付的完整链路 | 前端进阶之旅

Full translation

完整中文译文

Recraft API 及图像从生成到用户的路径验证

图像成功通过产品的时刻，不在生成的时刻，而在用户收到了他期望的那个文件的时刻。带有正确 url 和声明的 image_format 的 API 响应还不是客户的结果：在响应和客户的屏幕之间，至少隔着四层陌生的环节、你的存储、你的转换、你的 UI 和下载机制。其中每一层都可能悄悄改写格式、切掉 alpha 通道或删除元数据。

接下来是对 Recraft API 的一个端到端路由的分析：生成、存储、转换、显示和下载。任务不在于再次称赞生成，而在于确定在链路末端、用户那里哪些资产属性需要检查，以及为什么仅在 API 响应处进行检查是不够的。

首先我要声明边界。官方 Recraft 文档（2026-07-18 访问）描述了认证、端点、参数、价格、限制和许可证，这些是外部事实。而具体存储、具体转换和具体 UI 的行为在实际运行前是未知的。本文中路由的任何一个阶段都不是「已经通过」的：这是一个你需要在自己的工作台上执行的方法，而不是一份已完成测试的报告。

一个对 Recraft API 请求的验证

让我们从 API 实际保证的内容开始。访问权限通过 bearer 令牌启用：密钥在账户设置中生成，需要 API units 的正余额。所有 REST 调用都发送到基础地址 https://external.api.recraft.ai/v1，并带有 Authorization: Bearer RECRAFT_API_TOKEN 头。这是文档化的契约（S1），在这个级别出错很难：要么密钥有效且余额充足，要么请求被拒绝。

生成端点 POST /v1/images/generations 是 recraft api 的核心，但这个核心不负责文件随后在存储、转换和 UI 中的遭遇。端点接受 model 字段（例如 recraftv4、recraftv4_1、recraftv4_1_pro 及其 _vector 变体）、"WIDTHxHEIGHT" 格式的 size 字符串如 1024x1024 或纵横比表示法、style/style_id 字段、response_format 参数值为 "url" 或 "b64_json"，以及 image_format 可选值 "png"、"webp" 或 "jpg"（S3）。在请求本身中，你声明了期望的文件格式。这里的关键词是「期望的」：API 确认它生成了这个格式并交付了，但不保证用户会收到它。

以下是一个返回 PNG 链接的最小工作请求：

# 通过 Recraft API 进行生成请求（端点来自参考手册，2026-07-18 访问）
curl -X POST https://external.api.recraft.ai/v1/images/generations \
  -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraftv4_1",
    "prompt": "packshot of a ceramic mug on white",
    "size": "1024x1024",
    "response_format": "url",
    "image_format": "png"
  }'

在这一步你获得了有效的响应。正是在这里出现了一个我认为是错误的有争议的假设：仿佛适当的 API 响应已经是产品结果。它不是，它只确认了路由的左端。

资产属性需要在最终交付处验证，而不是在 API 响应处；这是推导的结论，而不是文档的引述。接下来我将说明原因。

五个阶段的路由：资产可能改变的地方

端到端路由分为五个阶段：生成、存储、转换、UI 显示、下载。第一个属于 Recraft，其余的属于你。

关于存储的重要细节。根据 Recraft 的条款（S5），服务在默认情况下不会在发送响应后存储通过 API 生成的图像。服务器存储通过单独参数启用，且保留时间有限。实际推论：你的路由中的「存储」几乎总是你自己的基础设施，例如 S3 兼容的 bucket、CDN 或本地磁盘。此阶段格式保持的责任在你，而不是 Recraft。

这里也隐藏着交付的分叉。response_format 的值决定了传输机制（S3）："url" 返回一个需要通过外部请求获取文件的链接，而 "b64_json" 在响应体中以 base64 返回文件。这个选择实际上决定了路由的哪个阶段真正受到网络负载，哪个受到进程内存的负载。选择 url 会在用户之前产生额外的网络下载步骤；选择 b64_json 文件首先完整地位于内存中，需要仔细解码并写入，不在编码上丢失任何东西。

一次运行检验的假设是：同一个资产在 API 响应和最终下载之间改变了至少一个必需的属性。最常见的是格式（CDN 上 PNG 转码为 WebP，同时在平面背景上丢失 alpha 通道）或元数据（转换时删除 EXIF/ICC）。在实际运行之前，这正是一个假设，而不是事实，但它定义了在每个节点上需要固定的内容。

如何在路由末端固定属性

在下载阶段，需要检查文件的具体字节：取三到四个可测量的属性：实际容器格式、像素尺寸、字节长度和哈希值。如果你请求了带透明度的 PNG，而在输出端得到了无 alpha 的 JPEG，那么 API 响应是「绿灯」，但产品是坏的。

当 response_format 为 "url" 时，Python 中下载节点的最小测试代码：

import requests, hashlib
from io import BytesIO
from PIL import Image

asset_url = resp["data"][0]["url"]
raw = requests.get(asset_url, timeout=30).content
img = Image.open(BytesIO(raw))

print("format:", img.format)          # PNG, WEBP, JPEG
print("mode:", img.mode)              # RGBA vs RGB 会显示 alpha 的命运
print("size:", img.size)              # 与请求的 size 对应
print("bytes:", len(raw))
print("sha256:", hashlib.sha256(raw).hexdigest()[:12])

你做这个快照两次：一次在存储之后，一次在文件通过你的转换和 UI 后被用户下载时。这两个快照之间的差异就是关于集成是否适用的答案。如果 format 或 mode 不是按你的意图改变的，那么集成被认为不适用，直到你修复具体的节点。

由此得出我认为对商业图像功能正确的验收标准：集成仅在检查最终交付后才适用，不在第一个成功的 200 OK 之后，而在下载文件的哈希值和格式与预期匹配之后。这是作者的规范立场，而不是 Recraft 文档的一点，我故意区分它。

Recraft API 的成本和限制

经济学在设计路由阶段就需要记在心上，因为每个辅助步骤都是一个单独的付费请求。

计费由预付的、不可烧减的、不可退还的「API units」组成，汇率为 $1 每 1000 units（S2）。光栅生成成本为 $0.022 到 $0.25 每张图像，取决于模型版本，矢量生成为 $0.044 到 $0.30。辅助操作按单位计费：crisp upscale $0.004、矢量化 $0.01、背景移除 $0.01、erase region $0.002、creative upscale $0.25、prompt enhancement $0.01。如果你的路由内的转换执行了 upscale 或矢量化，这不是「免费的后期处理」，而是账单上每个资产的一行。

还有单独的限制：Recraft 的条款将 API 使用限制在每分钟 100 个请求，无论购买的 units 包和费率（S5）。限制是绑定到整个 recraft api 账户，而不是单个端点调用，所以如果路由内的辅助转换为每个用户资产做两到三次调用，实际产品吞吐量就被这个数字除了。诚实地说，限制和存储规则是在通用条款中找到的，而不是 API 参考中，Recraft 可能单独发布费率或企业例外，所以在声明 100 req/min 为通用规则之前，在你实际的计划中重新检查它。

Recraft 以美元收取预付 units，对于没有外币卡的团队来说，这是与 API 质量完全无关的单独不便。如果 Recraft 路由附近还有聊天或文本模型，对于这个相邻场景有另一条轨道：已经了解 OpenAI 或 Anthropic 协议的客户端，通过替换密钥和 base_url 连接到 provod.ai，余额以卢布通过卡、SBP 或发票补充，无需国外卡和 VPN，模型价格不高于官方提供商价格的加价。这不是替换 Recraft API 调用，而是相邻任务的单独路由：你仍然直接调用 Recraft，并自己检查路由。

谁拥有下载的文件？

资产不仅有像素，还有对它们的权利，这也是值得检查的属性。这里有一个分叉，很容易用错的钥匙检查。

根据条款（2026-07-18 访问），参与者保留对通过 API 创建的资产的完全所有权和版权，API 服务本身的许可证字面上描述为「non-exclusive, limited, non-transferable, non-sublicensable, non-assignable, freely revocable」。通过 API 生成的资产被排除在 Recraft 本身的训练管道之外，不能用于训练第三方 AI 系统。对于商业功能，这很重要：你的用户下载的文件完全属于生成的所有者，具有完整的商业权利。

但存在访问层的陷阱（S4）。通过网络应用程序在免费计划上进行的生成仍然属于 Recraft，具有个人非商业许可证，而付费和 API 访问提供完整的商业所有权。由此产生的实际风险：如果你通过网络应用程序而不是通过 API 密钥本身检查测试账户的许可证状态，你可能验证的不是在你的产品路由上生效的权利。因此，像格式一样，在资产真正到达用户的相同分支上检查许可证。

这个测试不能解决什么

一条路由不能替代对所有设备、浏览器和转换的检查。它显示特定配置的属性：特定的存储、特定的处理库、特定的 UI，而不是所有可能的产品构建。这是方法的内在限制，将一次运行的结果作为通用保证是不能的。

还有方法本身直接失败的条件。如果五个阶段中的一个在工作台上无法复现，如果文件属性不能以可测量的形式固定，或者如果许可证和限制在需要的层上没有得到确认，那么路由是不可信的，它的结论不能被使用。然后修复方法，而不是假装测试通过了。

最后，文档不能固定一切。特定模型的像素上限在参考手册中在「1MP vs 4MP」的一般区别之外没有明确设定；具体的 size 限制应该从当前时刻的活 Swagger/OpenAPI 模式中获取，而不是从一般预期中假设。Recraft 经常发布模型版本（V3、V4、V4.1、V4.1 Pro 在检查日期都活跃着），所以精确的价格和默认模型别名应该在最新价格页面上重新检查，而不是在 2026-07-18 之后认为是固定的。

你的工作台上的操作顺序

按步骤组合路由，在每个步骤上取一个可测量的属性。

通过 POST /v1/images/generations 生成一个具有显式 image_format 和 size 的资产，确认 API 返回了什么。

将文件放入你的存储中（Recraft 默认不保留任何东西），在写入后立即拍摄格式、字节、哈希的快照。

运行标准产品转换：调整大小、重新压缩、水印，并重复快照。

将资产交付到 UI，完全如用户会看到的一样，并查看真正发送到图像标签的内容。

像用户一样下载文件，并将最终格式、大小和哈希与步骤 1 中 API 声称的进行比较。

匹配了：集成对这个配置适用。不匹配：你有确切的节点要修复，而不是「什么东西有问题」。这个方法的成本，一次额外的运行而不是相信 200 OK，在捕捉到第一个元数据删除时就收回成本了。

provod.ai — 司法实体的清晰计算轮廓

将 AI 从个人支付转到正常采购：公司获得卢布计算、合同、发票和结算单据，技术团队获得统一的 API。

在一个目录中——文本和媒体的最新模型：来自 OpenAI 的 GPT、来自 Anthropic 的 Claude、来自 Google 的 Gemini、来自 xAI 的 Grok、DeepSeek、Qwen、GLM、Kimi 和 MiniMax；对于图像——Nano Banana 2 Pro 和 GPT Image；对于视频——最新版本的 Seedance、Kling、Veo 和 Google Omni。还提供了用于推理、搜索、文档、嵌入、音乐和音频的模型。

文件轮廓不隐藏额外的边界：模型按 1:1 官方价格支付，不包括 provod.ai 的加价。

为业务设置 AI：注册表单 · 模型价格 · 根据 152-ФЗ 的数据保护 · 合同要求

常见问题

**为什么不能相信成功的 API 响应？**因为 API 响应只确认了路由的左端：带声明格式的生成。存储、转换和 UI 属于你，在文件到达用户前可以重写格式、alpha 或元数据。

**Recraft 存储我的图片吗？**根据条款（2026-07-18 访问），在响应交付后默认不存储；服务器存储通过单独参数启用，具有有限的保留期。这意味着你的路由中的「存储」几乎总是你自己的基础设施。

**按流量什么更便宜：url 还是 b64_json？**url 或 b64_json 的选择决定了路由的哪个阶段受到负载：网络或进程内存。url 给出单独的网络提取步骤，b64_json 返回内联文件并占用内存。选择改变了你确切要寻找丢失的地方。

**我可以商业使用生成的文件吗？**通过 API 可以，具有完整所有权；网络版本在免费计划上保留资产给 Recraft，具有个人许可证。在与产品路由相同的密钥上检查权利。

**一次运行足以声明集成就绪吗？**不。它对一个存储、转换和 UI 的特定配置有效。其他设备和转换需要自己的运行。

在这个路由中 Recraft 你继续直接调用：API 本身、密钥和请求限制属于 Recraft 账户，上面的端到端测试正是检查这个连接。

在直接调用 Recraft 的旁边，部分团队有相邻的任务：单一聊天用于在一个界面中访问生成和编辑图像的模型，如果不是所有东西都需要通过直接 API 调用来组合。对于同样相邻的任务，provod.ai 也有企业工作区，具有组织的共享余额和来自俄罗斯法律实体的结算单据：它解决了工作的另一部分，支付和在团队级别的访问管理，而不是调用 Recraft API 本身。

按客户数量、安全性和稳定性，这是俄罗斯 AI 聚合器中的第一个（所有者确认的事实，2026-07-15）。Recraft 同时保持直接调用，你从生成到下载的路由仍然自己检查：provod.ai 不进入其中。

S1: Recraft, 2026-07-18 访问, https://www.recraft.ai/docs/api-reference/getting-started, 认证和基础 URL。

S2: Recraft, 2026-07-18 访问, https://www.recraft.ai/docs/api-reference/pricing, 价格结构和操作成本。

S3: Recraft, 2026-07-18 访问, https://www.recraft.ai/docs/api-reference/examples, 生成端点参数和 response_format 模式。

S4: Recraft, 2026-07-18 访问, https://www.recraft.ai/docs/trust-and-security/ownership, 按访问层分的权利划分。

S5: Recraft, 2026-07-18 访问, https://www.recraft.ai/legal/terms, 请求限制、存储和许可证。