recraft-image-design

Recraft 图像设计

将 Recraft 用作设计制作系统，而不是通用提示词输入框。根据所需的输出规范选择模型和操作，只调用有文档说明的 API，并立即保存返回的素材，在交付前检查实际的栅格图像或 SVG。

证据标签与时效性

按字面理解标签：

• 有文档说明 — 见于 Recraft 第一方 API 参考、OpenAPI 文档、模型页面、法律页面或信任页面。
• 推断 — 根据有文档说明的行为得出的结论，但 Recraft 并未作出承诺。
• 生产经验法则 — 实用的工作流建议；请根据当前账户和需求进行测试。

本技能中的易变 API 信息已于 2026-07-09 核实。在成本较高或受监管的任务中使用前，请重新核实模型 ID、兼容性、定价、限制、数据保留和条款。应优先以人类可读的 API 指南作为依据。官方 Swagger 规范有时会列出指南未作说明的额外别名或字段；未经小规模验证请求测试，请勿依赖这些内容。

明确制作规范

调用 API 前，请记录：

1. 交付物：栅格图像或可编辑 SVG；
2. 目标宽高比、尺寸和最终用途所需分辨率；
3. 必须出现的确切文案（如有）；
4. 品牌配色、禁用颜色和风格参考；
5. 编辑中必须保持不变的内容；
6. 参考资料、人物、标记和文案的权利／同意状态；
7. 商业用途、来源／披露、隐私和数据保留要求；
8. 探索预算和验收检查项。

如果下游工具要求真正的路径，请选择矢量模型。看起来像矢量艺术的栅格图像不能替代 SVG。

选择当前模型

有文档说明，已于 2026-07-09 核实：POST /v1/images/generations 默认使用 recraftv4_1。公开指南接受以下 Recraft 专有模型 ID：

系列	栅格	矢量	用途
V4.1 表现力型，标准版	recraftv4_1	recraftv4_1_vector	当前默认选择，适用于概念设计、精致的艺术指导、字体设计、插画和一般制作
V4.1 表现力型，Pro 版	recraftv4_1_pro	recraftv4_1_pro_vector	同一系列，约 4 MP／更高输出尺寸，适用于印刷和精细细节
V4.1 实用型，标准版	recraftv4_1_utility	recraftv4_1_utility_vector	更简洁、扁平、正视且可预测的作品，例如产品图和模型图源素材
V4.1 实用型，Pro 版	recraftv4_1_utility_pro	recraftv4_1_utility_pro_vector	实用型表现，更高输出尺寸
V4	recraftv4	recraftv4_vector	上一代偏设计型系列
V4 Pro	recraftv4_pro	recraftv4_pro_vector	上一代高分辨率系列
V3	recraftv3	recraftv3_vector	适用于精选／自定义风格、本地化编辑路径、文本布局、负面提示词和艺术程度控制
V2	recraftv2	recraftv2_vector	适用于仅在 V2 中提供的旧版风格／效果

**有文档说明：**V4.1 于 2026 年 5 月中旬发布；V4 于 2026 年 2 月发布；V3 于 2024 年 10 月发布；V2 于 2024 年 2 月发布。Recraft 表示，全部 16 个专有变体仍可通过 API 使用。截至核实之日，未公布第一方弃用日期或正式支持期限。

**生产经验法则：**从 V4.1 标准版开始，以较低成本探索设计方向。仅将获批的构图升级到 Pro。若需求更看重可预测性而非戏剧性，请选择实用型。若 V3 的控制项属于硬性要求，请继续使用 V3，而不要试图用未经说明的 V4.1 字段模拟这些控制项。

重要的兼容性边界

• **文档说明：**在人类可读的兼容性表格中，V4 和 V4.1 系列不支持精选的 style、style_id、自定义风格创建、negative_prompt、V3 text_layout 或 artistic_level。请将视觉风格写入提示词，并使用受支持的颜色控制项。
• **文档说明：**V2/V3 支持命名风格。通过 API 创建的自定义风格适用于 V3/V3 Vector；必须在兼容的模型上重复使用某种风格。style 和 style_id 不能同时使用。
• **文档冲突：**当前图生图端点的说明称其支持 V3 和 V4，而其参数模型列表包含 V4.1 光栅/矢量变体。请将 V4.1 图生图视为“有文档说明但存在冲突”：在生产环境使用前，应在目标账户/合同中核实，或通过一项已纳入预算的验证请求进行确认。文档仅说明 V3/V3 Vector 支持局部 inpaint、outpaint、replaceBackground 和 generateBackground。
• **文档歧义：**较早的 V4 模型页面称不支持基于提示词的编辑，这进一步印证了当前端点指南自身说明与参数列表之间的不一致。不要将任何图生图支持结论扩展到局部编辑路由。
• **文档边界：**Recraft Studio 中展示的第三方模型不属于 Recraft 公共 API，即使内部 Swagger 枚举中可能包含其他名称。

API 契约

仅使用官方生产环境主机：

https://external.api.recraft.ai

每个受保护的请求都必须通过以下方式进行身份验证：

Authorization: Bearer $RECRAFT_API_TOKEN

切勿将令牌发送到资源 URL、用户提供的 URL、重定向目标、日志服务，或任何非 external.api.recraft.ai 的主机。请将其保存在环境变量中。切勿打印令牌。

核心路由

**文档说明，已于 2026-07-09 验证：**以下所有路由均位于 https://external.api.recraft.ai/v1 下。

方法和路径	用途	响应结构
POST /images/generations	光栅或矢量文生图	{"created":...,"credits":...,"data":[Image...]}
POST /images/generations/raster	请求体相同；强制使用光栅模型/风格	同上
POST /images/generations/vector	请求体相同；强制使用矢量模型/风格	同上
POST /styles	根据图像/来源风格创建 V3 自定义风格	风格对象及 credits
POST /images/imageToImage	由提示词引导的图像变体/转换	生成响应
POST /images/inpaint	填充白色蒙版区域	生成响应
POST /images/outpaint	扩展画布	生成响应
POST /images/replaceBackground	检测并替换背景	生成响应
POST /images/generateBackground	填充提供的背景蒙版	生成响应
POST /images/vectorize	将光栅图像转换为 SVG	{"created":...,"credits":...,"image":Image}
POST /images/removeBackground	移除光栅/SVG 图像的背景	图像处理响应
POST /images/crispUpscale	保持结构的光栅图像放大	图像处理响应
POST /images/creativeUpscale	通过再生成细节/面部进行放大	图像处理响应
POST /images/eraseRegion	擦除白色蒙版区域	图像处理响应
POST /images/variateImage	无提示词重混至目标尺寸	生成响应
POST /images/explore	生成多样化探索结果集	生成响应
POST /images/explore/similar	从 Explore 的 image_id 继续生成	生成响应
POST /prompts/enhance	扩展提示词，最多 2,000 个字符	{"enhanced_prompt":...,"credits":...}
GET /users/me	账户身份和单位余额	含 credits 的用户对象

官方 Swagger 还列出了风格/模型发现和风格删除路由。由于人类可读指南并未完整描述所有架构，GET /styles、GET /styles/basic、GET /styles/{style_id}、DELETE /styles/{style_id} 和 GET /models 均应视为Swagger 文档说明的路由，并在生产环境使用前进行功能探测。

生成请求

/images/generations 的 JSON 请求体使用以下字段：

字段	约定
prompt	必填字符串；V4/V4.1 最多 10,000 个字符，V2/V3 最多 1,000 个字符
model	上述某个公开模型 ID；默认值为 recraftv4_1
n	整数 1..6；按图像计费
size	支持的 WxH 或宽高比 w:h；如果省略，则根据提示词选择
random_seed	可选无符号整数；请记录下来以便重试
response_format	url（默认值）或 b64_json
style / style_id	仅限 V2/V3；不可同时使用
negative_prompt	仅限 V2/V3
text_layout	仅限 V3/V3 Vector
controls	所有文档所述的模型系列均支持调色板/背景；仅 V3 支持 artistic_level 和 no_text

**Swagger 有文档记录，指南中介绍较少：**光栅响应的 image_format 可设为 png 或 webp。矢量模型返回 SVG。不要假设 Studio 的导出格式（如 JPG、PDF、TIFF 或 Lottie）是 API 有效的 image_format 值。

Image 可以包含 image_id、url 或 b64_json、revised_prompt，以及可选的功能数据。解码或下载前，请先验证预期的负载字段是否存在。

尺寸

**有文档记录：**各模型系列支持的宽高比包括 1:1、2:1、1:2、3:2、2:3、4:3、3:4、5:4、4:5、6:10、14:10、10:14、16:9 和 9:16。

V4/V4.1 光栅模型的标准示例包括 1024x1024、1536x768、768x1536、1280x832、832x1280、1216x896、896x1216、1152x896、896x1152、832x1344、1280x896、896x1280、1344x768 和 768x1344。对应的 Pro 尺寸在每个轴上翻倍，包括 2048x2048、3072x1536 和 2688x1536。

V2/V3 光栅模型使用不同的明确尺寸表，例如 1024x1024、2048x1024、1024x2048、1536x1024、1024x1536、1820x1024 和 1024x1820。矢量模型接受有文档记录的宽高比标记，不保证像素尺寸。请查阅附录，不要自行推算任意尺寸。

图像输入和蒙版

接受图像的端点支持以下输入方式：

• 使用 image、mask 或 file 的 multipart/form-data；或
• 使用对应的 image_url 和 mask_url 的 application/json，URL 可以是公开 URL，也可以是 data:image/...;base64,... 数据 URL。

对于当前的变换路由，输入图像通常须为 PNG/JPG/WEBP 或 SVG，大小不超过 10 MB，像素数不超过 16 MP，最大尺寸为 4096 px，最小尺寸为 256 px。请检查具体操作：擦除和实用工具端点的限制各不相同。

对于局部重绘/生成背景的蒙版：

• 必须与源图像尺寸完全一致；
• 使用灰度 PNG/JPG/WEBP；
• 内容需要更改的区域使用纯白（255），保持不变的区域使用纯黑（0）；
• 上传前请排除抗锯齿和意外的灰色像素。

变换请求

/images/imageToImage 必须提供 image/image_url、prompt 和取值在 [0,1] 范围内的 strength；0 表示几乎完全相同，1 表示相似度最低。它还接受 n 1..6、模型、种子、响应格式，以及与模型兼容的控制项。

/images/inpaint 必须提供图像、蒙版和提示词。/images/generateBackground 使用相同的输入模式。/images/replaceBackground 必须提供图像和提示词。

/images/outpaint 必须提供图像和提示词，并且至少提供以下内容之一：

• size；或
• 一个或多个取值在 0..4096 范围内的 expand_left、expand_right、expand_top、expand_bottom；或
• 取值在 [0,100) 范围内的 zoom_out_percentage。

不要将 size 与 expand_* 同时使用。zoom_out_percentage 可以与其中任一项搭配使用。最终尺寸的任一边不得超过 4096 px。

/images/variateImage 必须提供图像和 size，接受 n 1..6、模型、种子和响应格式，不接受提示词。

矢量化和背景移除

/images/vectorize 接受 file 或 image_url，并返回 SVG 图像。Swagger 有文档说明、指南内容较少的矢量化选项包括 svg_compression、limit_num_shapes、max_num_shapes、颜色缩减、返回渐变、形状堆叠、小形状过滤和 strict_color_palette。由于指南未公开所有枚举值及其交互方式，除非已通过低成本测试验证当前 Swagger 架构，否则不要使用这些选项。

/images/removeBackground 接受栅格图像或 SVG。栅格输入会返回栅格图像；SVG 输入会返回 SVG。不要仅仅因为背景移除保留了 SVG 格式，就承诺其拓扑结构清晰且可编辑。

同步、批量和错误行为

• **公开文档中的契约：**端点调用会同步返回最终响应。n=1..6 是文档说明的多图请求方式。
• **仅见于营销材料的声明：**Recraft 的 API 产品页宣传异步任务、批量生成和优先推理。截至核验时，公开端点指南和已发布的 Swagger 均未公开任务提交、轮询、取消、Webhook、签名或优先级架构。不要臆造相关内容。实现这些功能前，请向 Recraft 获取企业合同。
• **文档说明的速率：**附录中规定每位用户每分钟 100 张图像、每秒 5 个请求；API 条款则单独规定每分钟 100 个请求。应同时限制图像数和请求数，并做好账户可能有专属调整的准备。
• **未公开的细节：**公开参考文档未提供稳定的错误响应正文或完整的状态码表。将所有非 2xx 响应视为失败；记录状态码、响应正文、响应标头和 X-Recraft-Requestid；如有 Retry-After，请遵循其指示。对于 429，以及经确认发生在请求传输前的连接失败，可采用有上限的退避和抖动重试。读取超时、提交后的超时、传输后连接中断以及 5xx 结果，都可能涉及计费或结果不明确：在重新提交前，应将其搁置，并通过本地账本或联系 Recraft 支持团队／查阅合同进行核对。不要盲目重试验证、身份验证或付款失败。
• 使用以你的任务 ID、提示词哈希、模型、种子和预期数量为键的幂等性账本。Recraft 未说明存在幂等键标头，因此提交后发生的超时可能意味着已计费但结果不明确。

直接控制设计

将提示词作为艺术指导规范

对于 V4/V4.1，请按以下顺序编写连贯的规范：

1. 交付内容和主体；
2. 构图和层级；
3. 材质、光线和渲染风格；
4. 用引号括起准确文本，并说明其作用；
5. 调色板及其与背景的关系；
6. 以肯定方式表述限制条件；
7. 预期用途和安全裁切区域。

避免罗列大量近义词。应说明元素之间的关系：“单个居中的组合标识”“标题占据上方三分之一”“三个物体，间距均匀”“纯色填充，无渐变”“相机正对包装”。

调色板和品牌一致性

文档说明：controls.colors 是一个对象数组，包含必填的 rgb: [r,g,b] 和可选的 weight（范围为 0..1）；颜色权重总和不得超过 1。controls.background_color 使用相同的颜色对象。这些控制项仅表示偏好，并不保证像素级精确。

**生产启发式做法：**在代码中将批准使用的品牌十六进制颜色值转换为 RGB，仅在必要时为主色分配较高权重，并将未分配的权重留给中性色。生成后验证采样得到的输出颜色。对于精确徽标或受监管的颜色，先生成周边设计，再使用确定性设计软件合成经批准的矢量图／徽标／颜色。

样式和子样式

有文档说明： V3 精选样式包括 Photorealism、Illustration 和 Recraft V3 Raw 等栅格类别，以及 Vector art、Line art 和 Engraving 等矢量类别。V2 还提供其他旧版效果。请以实时样式列表为准，因为名称和访问权限可能会变化。

Swagger 有文档说明，指南说明较少： 请求可能会公开 substyle，OpenAPI 中也包含大量枚举值。面向用户的 API 指南将这些内容归类为具名样式，并未保证所有原始枚举值和模型组合都可用。优先使用列表中提供的 style 或可访问的 style_id；仅在发现并通过验证请求后，才使用原始 substyle。

要创建 V3 自定义样式，请使用某个有文档说明的基础类型（any、realistic_image、digital_illustration、vector_illustration、icon、logo_raster），并提供最多 5 张 PNG/JPG/WEBP 参考图，调用 POST /styles。面向用户的指南将参考图总大小限制为 5 MB，且每个上传文件不得超过当前上传限制。指南还说明了可选的模型、图像权重、源样式 ID/权重、提示词，以及 PaletteMatch 或 MaxWeight 这两种 mix_policy。

仅使用你有权上传和转换的参考图。自定义样式并不意味着你可以复制受保护的艺术作品，或冒充在世艺术家。

文本和布局

对于 V4/V4.1，请将简短且必须准确的文案放在引号中，并描述层级和位置。对于较长的法律文案或要求像素级精确的排版，请先生成视觉底图，再使用确定性方法进行排版。

V3 的 text_layout 接受每个单词对应一个对象：

{
  "text": "RECRAFT",
  "bbox": [[0.20, 0.40], [0.80, 0.40], [0.80, 0.56], [0.20, 0.56]]
}

边界框必须恰好由 4 个 [x,y] 点组成，使用相对坐标，其中 (0,0) 为左上角，(1,1) 为右下角；坐标可以超出此范围，并会被裁切。API 规定了受限字符集。发送前请验证每个字符。单个 text 项中不要包含空格；每个单词应分别表示。

探索和可重复性

使用 random_seed 可让生成尝试具有可重复性，但不要认为 seed 或模型标签能在后端变更后提供存档级保证。请保存输出字节、请求 JSON、模型 ID、seed、时间、响应 ID、额度和内容哈希。

仅将 /images/explore 用于受支持的 V4/V4.1 expressive 和 Pro 模型。它会返回一组结果供视觉探索。/images/explore/similar 需要提供来自 Explore 的 image_id，以及 1..5 的相似度。探索可能需要在服务端临时生成资源；未确认保留政策前，不要将其用于敏感内容。

生产工作流

1. 预检： 通过 /users/me 验证令牌、API 单位余额、权利、输出类型、当前模型兼容性、速率预算和官方主机。
2. 试探： 以标准分辨率生成 n=1。立即保存请求、响应和素材。
3. 审查方向： 在增加开销前，检查需求、构图、文案、调色板、人体结构、品牌风险和不需要的内容。
4. 每次迭代一个变量： 更改提示词、模型、seed、调色板或操作，不要一次全部更改。记录更改原因。
5. 升级： 只有在方向获批后才使用 Pro；保持宽高比和艺术指导一致。
6. 收尾： 立即下载 URL，验证 MIME 类型/签名和尺寸，或安全地解析 SVG，然后计算哈希、扫描并存储在受控存储中。
7. 质量检查： 按预期显示尺寸和 100% 缩放进行审查；测试 SVG 的可编辑性、裁切、透明度和小尺寸可读性。
8. 交付溯源信息： 保留提示词、模型、seed、时间戳、Recraft 请求 ID/图像 ID、来源权限、编辑记录和披露决定。

栅格图像质量检查

• 主体数量和几何形状正确；
• 光照、反射和材质协调一致；
• 必需文案准确无误，且无多余文字；
• 主视觉元素未被裁切，构图可安全裁剪；
• 调色板、对比度和透明度/背景效果符合预期；
• 最终尺寸下的人脸、手部和产品没有缺陷；
• 已检查实际尺寸、文件签名、Alpha 通道和颜色配置文件。

Vector QA

• SVG 有效，并且在禁用脚本和外部引用的情况下完成解析；
• 除非明确接受，否则不嵌入栅格图像；
• 路径数量、分组、填充、描边和 viewBox 均合理；
• 没有意外裁切、未闭合的接缝、微小杂点或过多节点；
• 根据下游编辑需求转换或处理文本；
• 满足纯色和渐变要求；
• 在 favicon/图标尺寸下清晰易辨，在大尺寸下也保持整洁。

完整示例

以下示例仅供参考，并非必须遵循的固定公式。假设环境中已安装 curl、Python 3、Pillow、defusedxml，并设置了名为 RECRAFT_API_TOKEN 的环境变量。

示例 1 — 采用品牌色的 V4.1 栅格图像，安全持久下载

意图：创建一张 16:9 的活动主视觉，并使用克制的品牌调色板。V4.1 的风格通过提示词表达；controls 用于提供颜色偏好。

set -euo pipefail
: "${RECRAFT_API_TOKEN:?Set RECRAFT_API_TOKEN}"

curl --fail-with-body --silent --show-error \
  --connect-timeout 15 --max-time 180 --max-filesize 5000000 --remove-on-error \
  --dump-header response.headers \
  'https://external.api.recraft.ai/v1/images/generations/raster' \
  -H "Authorization: Bearer ${RECRAFT_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -o response.json \
  --data-binary @- <<'JSON'
{
  "prompt": "Editorial launch key visual for a precision ceramic travel mug, one mug centered slightly right with open copy space in the left third, camera square to product, soft directional daylight, tactile matte ceramic and brushed steel, calm premium composition, deep navy background with a restrained coral accent, no logos, no embedded words, no extra products, 16:9 crop-safe layout",
  "model": "recraftv4_1",
  "n": 1,
  "size": "16:9",
  "random_seed": 284771,
  "response_format": "url",
  "image_format": "png",
  "controls": {
    "colors": [
      {"rgb": [10, 31, 68], "weight": 0.55},
      {"rgb": [242, 101, 91], "weight": 0.20}
    ],
    "background_color": {"rgb": [10, 31, 68]}
  }
}
JSON

python - <<'PY'
import hashlib, io, json, pathlib, urllib.error, urllib.parse, urllib.request, warnings
from datetime import datetime, timezone
from PIL import Image

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

def open_https_without_auth(url, max_redirects=3):
    opener = urllib.request.build_opener(NoRedirect)
    current = url
    for _ in range(max_redirects + 1):
        parsed = urllib.parse.urlparse(current)
        if parsed.scheme != "https" or not parsed.hostname:
            raise SystemExit("Refusing non-HTTPS asset redirect")
        req = urllib.request.Request(current, headers={"User-Agent": "recraft-production-download/1"})
        try:
            return opener.open(req, timeout=120)
        except urllib.error.HTTPError as exc:
            if exc.code not in {301, 302, 303, 307, 308} or not exc.headers.get("Location"):
                raise
            current = urllib.parse.urljoin(current, exc.headers["Location"])
    raise SystemExit("Too many asset redirects")

r = json.loads(pathlib.Path("response.json").read_text(encoding="utf-8"))
item = r["data"][0]
url = item["url"]
u = urllib.parse.urlparse(url)
if u.scheme != "https" or not u.hostname:
    raise SystemExit("Refusing non-HTTPS asset URL")
with open_https_without_auth(url) as src:
    content_type = src.headers.get_content_type()
    body = src.read(50 * 1024 * 1024 + 1)
if len(body) > 50 * 1024 * 1024 or content_type != "image/png":
    raise SystemExit(f"Unexpected asset: {content_type}, {len(body)} bytes")
if not body.startswith(b"\x89PNG\r\n\x1a\n"):
    raise SystemExit("File signature does not match requested PNG")
warnings.simplefilter("error", Image.DecompressionBombWarning)
with Image.open(io.BytesIO(body)) as decoded:
    actual_size = decoded.size
    if actual_size != (1344, 768):
        raise SystemExit(f"Expected 1344x768 for standard 16:9, decoded {actual_size}")
    decoded.verify()
output = pathlib.Path("campaign-key-visual.png")
temporary = output.with_suffix(".png.tmp")
temporary.write_bytes(body)
temporary.replace(output)
pathlib.Path("campaign-key-visual.metadata.json").write_text(json.dumps({
    "submitted_request": {
        "prompt": "Editorial launch key visual for a precision ceramic travel mug, one mug centered slightly right with open copy space in the left third, camera square to product, soft directional daylight, tactile matte ceramic and brushed steel, calm premium composition, deep navy background with a restrained coral accent, no logos, no embedded words, no extra products, 16:9 crop-safe layout",
        "model": "recraftv4_1", "n": 1, "size": "16:9",
        "random_seed": 284771, "response_format": "url", "image_format": "png",
        "controls": {"colors": [{"rgb": [10, 31, 68], "weight": 0.55},
                                  {"rgb": [242, 101, 91], "weight": 0.20}],
                     "background_color": {"rgb": [10, 31, 68]}},
    },
    "response": r,
    "response_headers": pathlib.Path("response.headers").read_text(encoding="iso-8859-1"),
    "saved_utc": datetime.now(timezone.utc).isoformat(),
    "image_id": item.get("image_id"),
    "credits": r.get("credits"), "actual_size": actual_size,
    "sha256": hashlib.sha256(body).hexdigest(),
}, indent=2), encoding="utf-8")
PY

预期结果：一张标准分辨率的栅格图像，采用以藏青色为主的艺术指导，并在左侧留出文案空间。可能的问题：生成虚构的马克杯/Logo、留白不足或配色偏移。使用 Pro 之前，请先修正提示词或种子。

变体：获得批准后，将模型切换为 recraftv4_1_pro，保持宽高比、提示词和 controls 不变，并将本地预期尺寸断言从 (1344, 768) 更新为文档规定的 Pro 16:9 尺寸 (2688, 1536)。

示例 2 — 使用 base64 响应探索原生 SVG Logo

意图：生成可编辑的扁平矢量图形，不依赖可能过期的 URL。

set -euo pipefail
: "${RECRAFT_API_TOKEN:?Set RECRAFT_API_TOKEN}"

curl --fail-with-body --silent --show-error \
  --connect-timeout 15 --max-time 180 --max-filesize 30000000 --remove-on-error \
  --dump-header vector-response.headers \
  'https://external.api.recraft.ai/v1/images/generations/vector' \
  -H "Authorization: Bearer ${RECRAFT_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -o vector-response.json \
  -d '{
    "prompt": "Single centered symbol for a neighborhood seed library: an open seed pod forming a subtle letter S through negative space, flat vector geometry, two solid colors, bold silhouette, no gradients, no shadows, no mockup, no secondary symbols, no words, legible at 24 pixels",
    "model": "recraftv4_1_vector",
    "n": 1,
    "size": "1:1",
    "random_seed": 99214,
    "response_format": "b64_json",
    "controls": {"colors": [{"rgb": [20, 84, 63], "weight": 0.55}, {"rgb": [244, 184, 65], "weight": 0.30}]}
  }'

python - <<'PY'
import base64, hashlib, json, pathlib, re
from datetime import datetime, timezone
from defusedxml import ElementTree as ET

response_path = pathlib.Path("vector-response.json")
if response_path.stat().st_size > 30_000_000:
    raise SystemExit("Vector response exceeded transport cap")
r = json.loads(response_path.read_text(encoding="utf-8"))
raw = base64.b64decode(r["data"][0]["b64_json"], validate=True)
if len(raw) > 20 * 1024 * 1024 or b"<svg" not in raw[:4096].lower():
    raise SystemExit("Response is not a plausible SVG")
root = ET.fromstring(raw)
if root.tag.startswith("{"):
    namespace, local_root = root.tag[1:].split("}", 1)
else:
    namespace, local_root = "", root.tag
if local_root.lower() != "svg" or namespace not in {"", "http://www.w3.org/2000/svg"}:
    raise SystemExit("Root element is not SVG")
without_declaration = re.sub(br"^\s*<\?xml[^?]*\?>", b"", raw, count=1, flags=re.I)
if b"<?" in without_declaration:
    raise SystemExit("SVG contains a processing instruction")
allowed_tags = {
    "svg", "g", "defs", "title", "desc", "path", "rect", "circle", "ellipse",
    "line", "polyline", "polygon", "lineargradient", "radialgradient", "stop",
    "clippath", "mask",
}
allowed_attributes = {
    "id", "class", "viewbox", "width", "height", "x", "y", "x1", "y1", "x2", "y2",
    "cx", "cy", "r", "rx", "ry", "d", "points", "fill", "fill-opacity", "fill-rule",
    "stroke", "stroke-width", "stroke-linecap", "stroke-linejoin", "stroke-miterlimit",
    "stroke-dasharray", "stroke-dashoffset", "stroke-opacity", "opacity", "transform",
    "clip-path", "mask", "gradientunits", "gradienttransform", "spreadmethod", "offset",
    "stop-color", "stop-opacity", "preserveaspectratio", "href",
}
for element in root.iter():
    local_tag = element.tag.rsplit("}", 1)[-1].lower()
    if local_tag not in allowed_tags:
        raise SystemExit(f"SVG element is outside the passive allowlist: {local_tag}")
    for name, value in element.attrib.items():
        local_name = name.rsplit("}", 1)[-1].lower()
        lowered = value.strip().lower()
        if local_name.startswith("on") or local_name not in allowed_attributes:
            raise SystemExit(f"SVG attribute is outside the passive allowlist: {local_name}")
        if local_name == "href" and lowered and not lowered.startswith("#"):
            raise SystemExit("SVG contains an external/data reference")
        if "url(" in lowered and not re.search(r"url\(\s*['\"]?#", lowered):
            raise SystemExit("SVG contains a URL-based paint/reference")
        if "javascript:" in lowered or "data:" in lowered or "@import" in lowered:
            raise SystemExit("SVG contains active or embedded content")
output = pathlib.Path("seed-library-mark.svg")
temporary = output.with_suffix(".svg.tmp")
temporary.write_bytes(raw)
temporary.replace(output)
pathlib.Path("seed-library-mark.metadata.json").write_text(json.dumps({
    "submitted_request": {
        "prompt": "Single centered symbol for a neighborhood seed library: an open seed pod forming a subtle letter S through negative space, flat vector geometry, two solid colors, bold silhouette, no gradients, no shadows, no mockup, no secondary symbols, no words, legible at 24 pixels",
        "model": "recraftv4_1_vector", "n": 1, "size": "1:1",
        "random_seed": 99214, "response_format": "b64_json",
        "controls": {"colors": [{"rgb": [20, 84, 63], "weight": 0.55},
                                  {"rgb": [244, 184, 65], "weight": 0.30}]},
    },
    "response": r,
    "response_headers": pathlib.Path("vector-response.headers").read_text(encoding="iso-8859-1"),
    "saved_utc": datetime.now(timezone.utc).isoformat(),
    "image_id": r["data"][0].get("image_id"), "credits": r.get("credits"),
    "sha256": hashlib.sha256(raw).hexdigest(),
}, indent=2), encoding="utf-8")
PY

预期结果：包含紧凑双色标志的 SVG。可能的问题：嵌入了不需要的文本、节点过多，或在 24 px 下的轮廓不够清晰。请在矢量编辑器中检查并简化；生成结果并不代表已获得商标使用许可。

示例 3 — V3 蒙版修复，严格遵守蒙版语义

意图：仅替换栅格照片中选定的产品标签区域，同时保留其余部分。

输入：product.png 和尺寸完全匹配的二值 mask.png，其中标签区域为白色，其余区域为黑色。

set -euo pipefail
: "${RECRAFT_API_TOKEN:?Set RECRAFT_API_TOKEN}"

python - <<'PY'
import pathlib
from PIL import Image
for name in ("product.png", "mask.png"):
    path = pathlib.Path(name)
    if path.stat().st_size > 10 * 1024 * 1024:
        raise SystemExit(f"{name} exceeds 10 MB")
    with Image.open(path) as check:
        width, height = check.size
        if min(width, height) < 256 or max(width, height) > 4096 or width * height > 16_000_000:
            raise SystemExit(f"{name} is outside the documented dimension/pixel bounds")
        check.verify()
        if check.format != "PNG":
            raise SystemExit(f"{name} must actually be PNG for the declared MIME type")
with Image.open("product.png") as im, Image.open("mask.png") as mask_source:
    if mask_source.mode not in {"1", "L"}:
        raise SystemExit("The uploaded mask bytes must already be binary/grayscale")
    mask = mask_source.convert("L")
    if im.size != mask.size:
        raise SystemExit("Mask dimensions must equal source dimensions")
    if set(mask.getdata()) - {0, 255}:
        raise SystemExit("Mask must contain only pure black and white pixels")
PY

curl --fail-with-body --silent --show-error \
  --connect-timeout 15 --max-time 180 --max-filesize 70000000 --remove-on-error \
  --dump-header inpaint-response.headers \
  'https://external.api.recraft.ai/v1/images/inpaint' \
  -H "Authorization: Bearer ${RECRAFT_API_TOKEN}" \
  -F '[email protected];type=image/png' \
  -F '[email protected];type=image/png' \
  -F 'prompt=Minimal cream paper label with a small centered green leaf emblem, matching the existing bottle curvature, lighting, grain, and perspective; no readable words' \
  -F 'model=recraftv3' \
  -F 'n=1' \
  -F 'random_seed=44102' \
  -F 'response_format=b64_json' \
  -o inpaint-response.json

python - <<'PY'
import base64, hashlib, io, json, pathlib, warnings
from datetime import datetime, timezone
from PIL import Image
response_path = pathlib.Path("inpaint-response.json")
if response_path.stat().st_size > 70_000_000:
    raise SystemExit("Inpaint response exceeded transport cap")
r = json.loads(response_path.read_text(encoding="utf-8"))
raw = base64.b64decode(r["data"][0]["b64_json"], validate=True)
if len(raw) > 50 * 1024 * 1024:
    raise SystemExit("Inpaint output exceeds local 50 MiB safety limit")
if raw.startswith(b"\x89PNG\r\n\x1a\n"):
    suffix = ".png"
elif raw.startswith(b"RIFF") and raw[8:12] == b"WEBP":
    suffix = ".webp"
else:
    raise SystemExit("Unexpected inpaint output signature")
warnings.simplefilter("error", Image.DecompressionBombWarning)
with Image.open("product.png") as source:
    expected_size = source.size
with Image.open(io.BytesIO(raw)) as decoded:
    actual_size = decoded.size
    if (max(actual_size) > 4096 or actual_size[0] * actual_size[1] > 16_000_000
            or actual_size != expected_size):
        raise SystemExit(f"Unexpected inpaint dimensions: {actual_size}; expected {expected_size}")
    decoded.verify()
output = pathlib.Path("product-inpaint" + suffix)
temporary = output.with_suffix(output.suffix + ".tmp")
temporary.write_bytes(raw)
temporary.replace(output)
pathlib.Path("product-inpaint.metadata.json").write_text(json.dumps({
    "submitted_request": {
        "prompt": "Minimal cream paper label with a small centered green leaf emblem, matching the existing bottle curvature, lighting, grain, and perspective; no readable words",
        "model": "recraftv3", "n": 1, "random_seed": 44102,
        "response_format": "b64_json",
    },
    "input_sha256": {name: hashlib.sha256(pathlib.Path(name).read_bytes()).hexdigest()
                     for name in ("product.png", "mask.png")},
    "response": r,
    "response_headers": pathlib.Path("inpaint-response.headers").read_text(encoding="iso-8859-1"),
    "saved_utc": datetime.now(timezone.utc).isoformat(),
    "image_id": r["data"][0].get("image_id"), "credits": r.get("credits"),
    "actual_size": actual_size, "sha256": hashlib.sha256(raw).hexdigest(),
}, indent=2), encoding="utf-8")
PY

此示例仅使用 Pillow 验证蒙版。预期结果：选定的标签发生变化；未遮罩区域基本保持稳定。可能的问题：蒙版接缝、光照不匹配或出现不需要的文本。由于 API 要求使用二值像素值，因此无法通过灰色蒙版像素实现羽化；请调整选区形状并重新生成。

迁移与回退规范

将较旧的集成迁移到 V4.1 时：

1. 保存已批准的 V2/V3 输出和请求元数据快照；
2. 梳理所有已使用的字段和路由；
3. 将生成流程与 V3 专属风格、负面提示词、文本布局、艺术程度及局部编辑依赖分开；
4. 将纯文本转图像迁移到 recraftv4_1，或使用标准分辨率的 Utility；
5. 将风格意图转化为提示词，并保留调色板控制；
6. 使用一组固定的需求，在新旧模型上进行测试，并评估构图、文案、调色板、缺陷和成本；
7. 对必须使用 V3 专属操作的情况保留 V3 调用，不要悄悄丢弃控制项；
8. 仅在分辨率显著提升验收通过率时升级到 Pro；
9. 在资源清单中记录模型和请求架构的版本；
10. 关注官方更新日志/文档，并在更改默认设置前重新运行测试集。

不要悄悄将矢量替换为栅格图像、将 Pro 替换为标准版、将 Utility 替换为 Expressive、将修复替换为图生图，或将 API 路由替换为 Studio 模型图。请明确说明交付内容的变化，并取得批准。

安全、隐私、权利和来源信息

已记录的法律条款，已于 2026-07-09 核实： API 客户拥有通过 API 创建的资产；Recraft 将其可能拥有的任何版权转让给客户，供个人或商业用途，但须遵守相关规定，并严格禁止将资产用于训练 AI 模型／系统／网络。Recraft 针对 API 的信任声明指出，API 输入和输出绝不会用于模型训练；API 条款另行允许为客户支持、遵守法律和执行政策而进行必要处理。请将此 API 特例与一般 Studio 训练／退出机制区分开来。一般免费套餐的规则也不同：Free Tier Studio 资产归 Recraft 所有，仅限个人使用，不得用于商业用途。请勿将 Studio 免费套餐条款套用于付费 API 输出，反之亦然。

Recraft 授予的所有权并不代表已取得第三方许可。客户仍须对输入内容及其用途的权利负责，包括版权、商标、隐私、公开权和同意。请勿生成欺骗性冒充内容、可识别个人身份的数据、辱骂／违法内容、对儿童的剥削、未经同意的私密影像、有害的虚假信息、支持恐怖主义的内容，或针对受保护群体的暴力内容。涉及人物、商标、受监管声明、政治说服和高风险用途时，应进行人工／法律审查。

已记录的隐私／保留政策： 第一方页面的说法并不完全一致。API 条款称，默认情况下，Recraft 不会在交付后继续存储 API 图像／元数据；而 API 附录和信任文档则称，生成结果会在约 24 小时内存储／删除。探索／迭代功能可能会暂时保留生成内容，可选的保留设置也可能延长存储时间。请遵循保守原则：假设处理及签名链接最长可用约 24 小时，立即下载，切勿将 Recraft URL 当作私密存储；在处理敏感工作负载前，请向 Recraft 确认合同条款。

已记录： URL 输出无需身份验证，任何持有经过加密签名 URL 的人都可以访问。请勿在提示词／图像中放入秘密、尚未发布的机密设计、生物识别数据或不必要的个人数据。如果无法接受链接泄露，请优先使用 b64_json，同时注意服务提供商仍会处理相关内容。

已记录的来源信息条款： Recraft 可能嵌入机器可读的元数据、水印或来源信息。除非法律明确允许，否则请勿移除或更改 Recraft 添加的来源信息。用户有责任遵守法律规定的 AI 披露要求。Recraft 未公开承诺每项 API 输出都包含 C2PA；请检查实际资产，并独立保存来源记录。

费用与访问概览

已核实的 API 价格，核实日期：2026-07-09： API 单位需预先购买，每 1 美元可购买 1,000 个单位，且永不过期；套餐不可取消或退款。当前按输出计费的费用包括：

操作	美元 / 单位
V4.1 或 V4.1 Utility 栅格图	$0.035 / 35
V4.1 Pro 或 Utility Pro 栅格图	$0.21 / 210
V4 栅格图 / V4 Pro 栅格图	$0.04 / 40；$0.25 / 250
V3 栅格图 / V2 栅格图	$0.04 / 40；$0.022 / 22
V4.1/V4 标准矢量图	$0.08 / 80
V4.1/V4 Pro 矢量图	$0.30 / 300
V3 矢量图 / V2 矢量图	$0.08 / 80；$0.044 / 44
V3 栅格图/矢量图图生图、局部重绘、扩图、背景操作	$0.04 / 40；$0.08 / 80（每张图）
创建风格	$0.04 / 40（每次请求）
矢量化 / 移除背景	各 $0.01 / 10
清晰放大 / 创意放大 / 擦除 / 变体生成	$0.004 / 4；$0.25 / 250；$0.002 / 2；$0.04 / 40
提示词增强	$0.01 / 10

更新期间，公开 API 价格页面与一般营销价格可能会短暂不一致。运行前请以 API 价格页面和 /users/me 为准。预估单位数时，将每项操作的费用乘以请求的输出数量，再预留重试和歧义处理所需的额度；达到预算后停止。

当前价格表仅列出 V3/V3 Vector 的图生图价格，且未列出 Explore/Explore Similar 的费用，尽管端点指南公开了更广泛的图生图模型参数和 Explore 路由。/users/me 会报告余额，但不会提供缺失的操作价格。在为 V4/V4.1 图生图或 Explore 工作负载编制预算前，请获取 Recraft 支持团队/销售团队的书面确认。

第一方来源

核实日期：2026-07-09：

• API 入门指南和模型 ID：https://www.recraft.ai/docs/api-reference/getting-started
• 端点指南和架构：https://www.recraft.ai/docs/api-reference/endpoints
• 官方示例：https://www.recraft.ai/docs/api-reference/examples
• 风格和兼容性：https://www.recraft.ai/docs/api-reference/styles
• 尺寸、提示词限制、速率和 URL 政策：https://www.recraft.ai/docs/api-reference/appendix
• API 价格：https://www.recraft.ai/docs/api-reference/pricing
• 官方 Swagger 首页/规范：https://external.api.recraft.ai/doc/
• V4.1 系列：https://www.recraft.ai/docs/recraft-models/recraft-v4-1
• 模型选择：https://www.recraft.ai/docs/recraft-models/choosing-a-model
• Studio 样机（非 API 路由）：https://www.recraft.ai/docs/recraft-studio/mockups/how-to-create-a-mockup
• 条款、API 所有权、数据保留、来源证明和限制：https://www.recraft.ai/legal/terms
• 隐私政策：https://www.recraft.ai/legal/privacy
• API 数据使用/训练：https://www.recraft.ai/docs/trust-and-security/data-use-and-model-training
• 数据保护和 API 删除声明：https://www.recraft.ai/docs/trust-and-security/data-protection-and-privacy

明确不可用或存在歧义的信息

核实时，第一方公开资料未提供以下信息：

• 正式的模型弃用日期或生命周期保证；
• 尽管营销材料有所声称，但未提供公开的异步/批处理任务、轮询、取消、Webhook、签名或优先级推理架构；
• 完整且稳定的错误代码/响应正文约定；
• 幂等键保证；
• 公开 API 指南中的生成延迟或正常运行时间 SLA；
• 用于 Studio 样机图层变形/合成的公开 API 端点；
• 对每个 API 输出都提供通用来源证明/C2PA 的保证；
• 法律、附录和信任页面之间完全一致的默认数据保留声明。
• 当前端点说明与模型参数列表之间经过协调的 V4.1 图生图兼容性说明；
• 已发布的 V4/V4.1 图生图或 Explore/Explore Similar 操作价格。

请勿自行猜测字段或路由来填补这些信息空缺。如果这些要求对生产环境至关重要，请向 Recraft 支持团队/销售团队索取书面约定。