Recraft V4.1 API 怎么用？5 分钟跑通配色出图

TL;DR

• Recraft V4.1 系列是参数完全一致的一对文生图模型：recraft-v4.1/text-to-image 出细节更足的终稿（$0.05/张），recraft-v4.1-flash/text-to-image 快速试稿（$0.01/张），只差一个 model 字段。打开模型页就能试，新用户注册送 200 积分。
• 特色是品牌配色：colors 传一组 RGB，画面尽量落在这组颜色里（Playground 暂不提供，走 API）。
• 调用走 HiAPI /v1/tasks 接口：提交任务拿 taskId，再查询结果，成功后从 output[0].url 下载。

它能做什么

• 摄影、插画、海报都出：写实产品图、扁平矢量插画、带标题的海报，一句描述直达。
• 配色可控：colors 指定调色板、background_color 指定底色，做品牌物料时贴住 VI。
• 6 种尺寸预设：square_hd（默认）、square、portrait_4_3、portrait_16_9、landscape_4_3、landscape_16_9，无自定义宽高。
• Flash 试稿 + V4.1 定稿：参数一样、只换 model，10 张试稿加 1 张定稿 $0.15。

下面是 V4.1 的真实成品：

Minimalist brand poster for a specialty coffee brand, huge bold headline "NORTH BEAN" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout

（中文意思：极简风精品咖啡品牌海报，巨大的粗体无衬线标题 "NORTH BEAN"，暖赤陶与奶油色配色，单颗咖啡豆插画，大量留白，瑞士网格版式。尺寸选 portrait_4_3。）

recraft-v4.1/text-to-image，portrait_4_3，本文示例图 896×1216，$0.05。

用这个提示词生成 →

两个模型怎么选

两个模型同一条流水线：Flash 出 10 个方向 $0.10，选中的那条换 model 重跑成 V4.1 终稿 $0.05，一套 $0.15。反过来只出草图时全程 Flash，1,000 张也只要 $10.00。按场景挑提示词看提示词大全。

两条上手路线

浏览器 3 步：打开模型页 → 粘贴提示词、选尺寸 → 点生成，V4.1 一张 $0.05。（colors 和 background_color 要走 API。）第一次建议先在浏览器跑一张，确认风格合预期再写代码。

API 3 步：POST /v1/tasks 提交 → 拿 taskId → GET /v1/tasks/<taskId> 查到 success 后下载。

curl：第一张（带品牌配色）

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "recraft-v4.1-flash/text-to-image",
  "input": {
    "prompt": "Flat vector illustration of a cozy reading nook with an armchair, a tall plant and a round window showing a city skyline at dusk, clean geometric shapes, gentle grain",
    "image_size": "landscape_4_3",
    "colors": [
      {"r": 28, "g": 61, "b": 90},
      {"r": 240, "g": 128, "b": 60},
      {"r": 245, "g": 222, "b": 179}
    ],
    "background_color": {"r": 250, "g": 246, "b": 238}
  }
}'

这条用的是 Flash 案例的真实参数：深蓝、橙、麦色三色调色板加米白底色。出终稿把 model 换成 recraft-v4.1/text-to-image，其余不动。

Python：提交、轮询、下载

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "recraft-v4.1/text-to-image",
    "input": {
        "prompt": "Minimalist brand poster for a specialty coffee brand, huge bold headline \"NORTH BEAN\" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout",
        "image_size": "portrait_4_3",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 临时地址，尽快下载保存
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

参数表（两个模型一致）

每个 RGB 对象 r/g/b 三键都必填、各 0–255、不能多键。请求体里出现表外字段会直接 400。

你会遇到的报错（接口原文）

（原文取自 Flash 的同套校验记录；V4.1 参数结构相同。）同一个 Idempotency-Key 重复提交返回 409 或 422，换新 key 再试。

上线前注意

• 回调：请求体顶层传 "callback": {"url": "https://..."}，终态自动通知。
• 及时转存：output[0].url 是临时地址，拿到就下载存进自己的存储，别把它当永久链接用。
• 配色是引导不是锁定：提示词里写了和 colors 冲突的颜色时，结果可能混合两者；要严格贴色就别在提示词里写别的颜色。
• Flash→V4.1 只换 model：其余参数原样保留，构图思路直接复用。

常见问题

• 是的，两个模型参数完全一样，只换 model 字段，代码零改动。
• 是的，colors 只能走 API，Playground 暂不提供这两个参数。
• 不是，colors 不保证只用这些颜色：它是强引导，画面尽量落在该组色里。
• 是的，一次 1 张；要多张多提交或排队。
• 是的，$10 就能开始：Flash $0.01 一张，$10 出 1,000 张，试错成本极低。
• 是的，6 种尺寸同价：正方、竖版、横版一个价，按平台选就行，不用为画幅算差价。
• 不是，colors 不限张数清单里的色数：传几个 RGB 都行（schema 没写上限），两三个主色加一个底色是最常用的配法。
• 是的，失败不扣费。 参数校验不通过直接 400 不进计费；任务到失败终态预扣全额退还。

下一步：拿 NORTH BEAN 提示词去模型页出一张，需要贴品牌色时把 colors 加进 API 请求；场景模板看提示词大全。