Recraft API 接入：官方端点、鉴权与风格一致性

Recraft 有官方 API，账上有余额的账号都能调。整套接口是 REST，基址只有一处：https://external.api.recraft.ai/v1。能不能接进你的流水线，取决于两个问题：请求里送哪条模型线，以及风格在请求体里怎么表达。

官方 Recraft API 提供了什么

官方文档写明，五条模型线共 20 个模型都可以在 API 里调用：V2、V3、V4、V4.1，以及独立的 V4 Styles。这些模型之上有十五项能力：文生图、创建风格、图生图与遮罩编辑、背景替换与生成、矢量化、放大、remix、提示词增强，以及一个返回余额的账户接口。

客户端这层很薄。所有请求都是 REST，官方推荐用 OpenAI Python 库对接，同时附了一句必须当真的警告：并非所有参数都受支持，有些参数含义不同，还有一些会被静默忽略。参数没生效却不报错，是最难查的一类问题。Recraft 主题总览页汇总了各条模型线的官方定位。

拿令牌与端点分布

鉴权头

令牌是 Bearer token，在 app.recraft.ai/profile/api 生成，放进 Authorization: Bearer $RECRAFT_API_TOKEN。官方写明一个前提：只有 API units 余额大于 0 时，生成按钮才可用。一个账号可以建多个令牌，但它们共用同一个余额。

端点面

所有已公布的操作都是同一个域名上的 HTTP POST。响应形态只有三种：/v1/images/generations 返回 data[].url；矢量化、去背景与两个放大接口返回 image.url；/v1/styles 返回 {"id": "..."}。

第一条生成请求

# 需要 curl 与 jq。
# 1. V4.1 是官方默认模型，这里的 model 可以省略。
curl https://external.api.recraft.ai/v1/images/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -d '{
        "prompt": "four race cars on a track, editorial light",
        "model": "recraftv4_1",
        "n": 2,
        "response_format": "url"
    }'

# 2. 精选风格用 style 按名称传，并把 model 钉在
#    收录该名称的那条线上。
curl https://external.api.recraft.ai/v1/images/generations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -d '{
        "prompt": "a monster with lots of hands",
        "model": "recraftv3",
        "style": "Hand-drawn",
        "style_match": "regular"
    }'

四个字段值记住就够用。n 取值 1 到 6，默认 1。model 默认是 recraftv4_1，加 _vector、_pro、_utility 后缀换的是同一条家族里的变体，不是另一个产品。size 可以写 WxH，也可以写 16:9 这类比例，不填时由提示词推断。response_format 取 url 或 b64_json。

API 上的风格一致性怎么表达

多数团队看这套 API 就是为了风格，而文档把它分成三条路，三条路不能互换。

精选风格：style 参数

精选风格按名称调用，例如 Hand-drawn、Photorealism、Vector art。同一个名称挂在多条模型线上时，API 会解析到其中一条，所以版本要紧就把 model 写死。返回格式也是写明的：Photorealism 出栅格，Vector art 出 SVG。style 与 style_id 都不传，就用该模型的默认风格，默认值以 UUID 形式公布。

自定义风格：style_id 与参考图

品牌风格真正落脚在 style_id 上。官方给了三条获取路径：调用 POST /v1/styles；在生成请求里带参考图，让响应把解析出的 style_id 返回；或者在网页端的 Styles 面板用三点菜单复制，前提是这个风格归你所有，或已被分享到你的账号。

有两条互斥规则要写进客户端代码：同一个请求里既有 style_id 又有参考图会被拒绝；V4 Styles 这条线更严，两者都不给同样被拒。style_match 决定跟随风格的字面程度，V4 与 V4.1 上取 precise 或 flexible，V2 与 V3 上取 regular。

把一种风格固定在一批图上

# 需要 curl 与 jq。
BASE=https://external.api.recraft.ai/v1

# 1. 创建一次风格，把 id 留下来。
STYLE_ID=$(curl -s -X POST "${BASE}/styles" \
    -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
    -F "model=recraftv4_styles" \
    -F "file1=@reference-1.png" \
    -F "file2=@reference-2.png" | jq -r .id)

# 2. 批次里每一次生成都带同一个 style_id。
index=0
for prompt in "product hero shot, bottle on a table" "bottle on a marble ledge, morning light"; do
  curl -s "${BASE}/images/generations" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
      -d "{\"prompt\": \"${prompt}\", \"model\": \"recraftv4_styles\", \"style_id\": \"${STYLE_ID}\", \"style_match\": \"precise\", \"n\": 2, \"response_format\": \"url\"}" \
    | jq -r '.data[].url' | while read -r url; do
      index=$((index + 1))
      curl -sL -o "recraft-${index}.webp" "${url}"
    done
done

创建风格要用 model=recraftv4_styles，因为风格记录的是它创建时所用的模型，后续生成必须匹配。改为在生成请求里直接附参考图，就省掉这次往返，服务端会私下建好风格并把它的 id 返回来复用。计费上，创建风格收一次，生成按张收，响应里的 credits 是两者之和。

编辑、矢量化与放大

编辑类能力会让模型线的选择变成硬约束。局部重绘、扩图与背景类操作只在 V3 上运行，用于把文字放到精确位置的 text_layout 也只有 V3 支持，negative_prompt 同样只写给 V2 与 V3。V4 与 V4.1 只部分支持自定义调参，V4.1 文档里点名的是 colors 与 background_color。

工具类端点收的是图片而不是提示词，也不挑模型线：/v1/images/vectorize 出矢量图，/v1/images/removeBackground 出抠图，清晰放大与创意放大的区别在于是否重绘内容。网页端上手指南讲的是同一批操作在界面里的做法，Nano Banana 笔记与 GPT Image 笔记讲的是纯栅格那条路。

官方没有公布的部分

文档在字段上写得很细，在运营层面基本沉默。下面这些都没有公布数字，请按缺口做设计，不要自己填一个：

• 各端点的速率限制、并发上限与吞吐承诺。
• 令牌的有效期、轮换与吊销策略。
• 各端点的延迟，以及网关强制的超时。
• SLA 数值，Enterprise 也不例外。
• 生成是否同步：示例直接从响应里取结果，文档里也没有出现 operation id，但官方从未把这句话写实。
• 某个计划具体怎么购买 API units，除了汇率与「余额需大于 0」这条前提之外。
• V4 Styles 基准测试的完整方法学，官方说法是「索取可得」。

转售 Recraft 访问权的第三方网关不是官方渠道。它们的价格与能力说明由各自站点发布，本文不引用。

API units 与单次请求成本

定价页只公布一个汇率：1.00 美元 = 1,000 API units，按张、按变体计费。充值包需要预付，不可取消、不可退款，且不过期。

编辑类比生成便宜：矢量化与去背景 $0.01，清晰放大 $0.004，擦除区域 $0.002，提示词增强 $0.01，remix $0.04，创建风格一次性 $0.005。创意放大是异类，要 $0.25；矢量批次的成本约为栅格的两倍。

常见问题

Recraft API 是官方的吗？ 是。文档在 Recraft 自己的域名下，含 Bearer 鉴权、端点参考、API 主机上的 Swagger UI，以及按张计的 API units 价格。

令牌在哪里获取？ 在 app.recraft.ai/profile/api。官方写明的前提是 API units 余额大于 0，同一个余额被所有令牌共用。

怎么让一批图保持同一种风格？ 用 /v1/styles 建风格，把返回的 style_id 带进每一次生成；或者在请求里附参考图，复用响应返回的 style_id。两者同时出现会被拒绝。

默认该用哪个模型？ recraftv4_1。需要局部重绘、扩图、背景类操作，或把文字放到精确位置时换 V3，文档把这些标为 V3 专属。

需要轮询结果吗？ 文档没有提 operation id，也没有轮询步骤，官方示例直接从响应读结果。单次请求延迟未公布，超时按自己的客户端设置。

把余额充上，把模型 ID 放进配置，在写 worker 之前决定用精选名称还是 style_id。这三件事基本覆盖了第一次接 Recraft 会踩的坑。

发布于

2026年9月13日

信息核验

2026年9月13日

作者

AI Tool Blog 编辑部