跳转到内容
HiAPI Docs
HiAPI
在线试用 获取 API Key
中文
English 中文

Recraft V4 Styles Pro API

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

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

模型概览

模型名称 recraft-v4-styles-pro/text-to-image
类型 图像生成（风格参考文生图，高分辨率）
接口 POST /v1/tasks
价格 见 HiAPI 定价

Recraft V4 Styles Pro：用 1–10 张参考图定下画风，生成分辨率更高的同风格新图片（square_hd 示例为 2048×2048），每次 1 张。

生产建议

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

适用场景

海报与印刷

需要大尺寸原图的海报、展板和印刷物料。

image_urlsimage_size
品牌视觉延展

用现有品牌插画作参考，需要时用 colors 固定品牌色。

image_urlscolors
系列插画定稿

同一组参考图 + 不同提示词，出需要放大展示的定稿。

image_urlsprompt

请求参数

model string 必填

固定填 recraft-v4-styles-pro/text-to-image。

示例 recraft-v4-styles-pro/text-to-image
input object 必填

业务参数对象。

prompt string 必填

要画的内容，1–10000 个字符。画风由 image_urls 决定。

image_urls array 必填

1–10 张风格参考图的公网 http(s) 地址。PNG、JPG 或 WEBP，每张小于 20 MB，合计不超过 64 MB，不支持 SVG。

image_size enum 可选

输出尺寸预设。

默认 square_hd 可选值: square_hdsquareportrait_4_3portrait_16_9landscape_4_3landscape_16_9
style_match enum 可选

贴近参考画风的程度：precise 更贴近，flexible 允许更多变化；不传时按 flexible。

可选值: flexibleprecise
colors array 可选

可选，希望画面使用的配色，RGB 对象数组。

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

用例示例

两张水彩参考图 + 一句提示词

两张地中海风景水彩作参考，提示词写悬崖灯塔和海鸥；输出 2048×2048，沿用参考图的淡彩和水彩晕染。

请求体
{
  "model": "recraft-v4-styles-pro/text-to-image",
  "input": {
    "prompt": "A lighthouse on a cliff with seagulls and waves, no logos, no brand names",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/fa10ab95992be1a3.png",
      "https://static.hiapi.ai/gallery/2026/10/e96f0a8de9568541.png"
    ],
    "image_size": "square_hd"
  }
}

获取结果

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

常见问题

必须传参考图吗？

必须。image_urls 至少 1 张、最多 10 张。

参考图有什么要求？

PNG、JPG 或 WEBP 的公网 http(s) 地址，每张小于 20 MB，合计不超过 64 MB，不支持 SVG。

style_match 怎么选？

precise 更贴近参考画风，flexible 允许更多变化；不传时按 flexible。

支持哪些尺寸？

image_size 可选 square_hd（默认）、square、portrait_4_3、portrait_16_9、landscape_4_3、landscape_16_9。square_hd 示例输出 2048×2048。

和 Recraft V4 Styles 有什么区别？

参数相同，Pro 输出分辨率更高：同样用 square_hd，Styles 示例输出 1024×1024，Pro 示例输出 2048×2048。价格以实时价格为准。

能指定配色吗？

可以，通过 API 传 colors（RGB 对象数组）和 background_color（RGB 对象）。在线 Playground 暂不显示这两个参数。

能复用已保存的风格吗？

目前不支持传入已保存的风格，每次请求都要带参考图。

一次生成几张？

每次请求生成 1 张图片，通过任务结果里的 output[].url 下载。

下一步