Recraft V4.1 Text to Image API

POST Base URL: https://api.hiapi.ai /v1/tasks

图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称	recraft-v4.1/text-to-image
类型	图像生成（文生图）
接口	POST /v1/tasks
价格	见 HiAPI 定价

Recraft V4.1：输入一句描述，生成细节更足的摄影、插画和海报，还可以指定配色和背景色。

生产建议

生产环境建议

生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
产物 URL 有有效期，拿到结果后请及时转存到自己的存储。

适用场景

营销配图

海报、社媒配图和横幅，按尺寸预设直接出图。

promptimage_size

品牌插画

用 colors 和 background_color 锁定品牌配色。

colorsbackground_color

成品视觉

细节和光线更讲究，适合直接交付的海报和产品图。

prompt

请求参数

POST https://api.hiapi.ai/v1/tasks

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
# 把 YOUR_API_KEY 换成你的账号 API Key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "recraft-v4.1/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
    }
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "recraft-v4.1/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
    }
  }
}
''')

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # 成功返回 { code, message, data: { taskId } }

// 提交异步任务，成功立即返回 taskId（不等待生成完成）
// 把 YOUR_API_KEY 换成你的账号 API Key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "recraft-v4.1/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
    }
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

固定填 recraft-v4.1/text-to-image。

示例 recraft-v4.1/text-to-image

input object 必填

业务参数对象。

prompt string 必填

图片描述，1–10000 个字符。

image_size enum 可选

输出尺寸预设。

默认 square_hd 可选值: square_hdsquareportrait_4_3portrait_16_9landscape_4_3landscape_16_9

colors array 可选

可选，希望画面使用的配色，RGB 对象数组；每个对象含 r、g、b，取值 0–255。

r integer 必填

0–255，红

g integer 必填

0–255，绿

b integer 必填

0–255，蓝

background_color object 可选

可选，希望的背景色，RGB 对象；r、g、b 取值 0–255。

callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback

when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

用例示例

指定配色的扁平插画

用 colors 指定深蓝、橙和麦色，background_color 指定米白，画面整体落在这组配色里。

请求体

{
  "model": "recraft-v4.1/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
    }
  }
}

获取结果

提交成功后立即返回 taskId（不等待生成完成）。
生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
status=success 后，从返回的 output[].url 下载图片。
如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

Recraft V4.1 和 V4.1 Flash 有什么区别？

V4.1 更注重细节和完成度，Flash 更快，适合批量试稿。

支持哪些尺寸？

image_size 可选 square_hd（默认）、square、portrait_4_3、portrait_16_9、landscape_4_3、landscape_16_9 六种。

怎么指定配色？

通过 API 传 colors（RGB 对象数组）和 background_color（单个 RGB 对象），每个通道取值 0–255。在线 Playground 暂不提供这两个参数。

一次能生成几张？

每次请求生成 1 张图片。需要多张时分别提交多个任务。

输出是什么格式？

返回 1 张图片，通过任务结果里的 output[].url 下载。

画面里的文字写得准吗？

短标题通常比较准确。把文字用引号写进提示词，并说明位置和字体风格，效果更稳定。

需要上传参考图吗？

不需要，这是纯文生图模型，只需要文字描述。