Recraft V4 Pro Vector API

Q: 需要上传参考图吗？

不需要，这是纯文字生矢量模型。

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

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

模型概览

模型名称	recraft-v4-pro/text-to-vector
类型	图像生成（文生矢量 SVG）
接口	POST /v1/tasks
价格	见 HiAPI 定价

Recraft V4 Pro Vector：同一句描述生成更精细的可编辑 SVG，适合成品 Logo、复杂图标和矢量插画。

生产建议

生产环境建议

生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
产物 URL 有有效期，拿到结果后请及时转存到你自己的存储。
输出是 SVG 矢量文件；如果业务只需要栅格图片，请在拿到文件后自行栅格化，不要按图片字节流直接当 JPEG/PNG 使用。

适用场景

成品 Logo

需要多层结构、负空间和精细轮廓的品牌标志。

promptcolors

复杂图标组

同一套视觉语言下的多对象图标，放大后仍经得起看。

promptimage_size

精细矢量插画

海报、包装和编辑配图，可直接进入印前流程。

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-pro/text-to-vector",
  "input": {
    "prompt": "A detailed flat vector illustration of a coastal town at golden hour: terraced houses on a cliff, fishing boats in the harbor, seagulls, layered waves. Limited palette of coral, navy, sage and cream, crisp geometric shapes, strong silhouettes, no gradients",
    "image_size": "square_hd"
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "recraft-v4-pro/text-to-vector",
  "input": {
    "prompt": "A detailed flat vector illustration of a coastal town at golden hour: terraced houses on a cliff, fishing boats in the harbor, seagulls, layered waves. Limited palette of coral, navy, sage and cream, crisp geometric shapes, strong silhouettes, no gradients",
    "image_size": "square_hd"
  }
}
''')

# 提交异步任务，成功立即返回 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-pro/text-to-vector",
  "input": {
    "prompt": "A detailed flat vector illustration of a coastal town at golden hour: terraced houses on a cliff, fishing boats in the harbor, seagulls, layered waves. Limited palette of coral, navy, sage and cream, crisp geometric shapes, strong silhouettes, no gradients",
    "image_size": "square_hd"
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

固定填 recraft-v4-pro/text-to-vector。

示例 recraft-v4-pro/text-to-vector

input object 必填

业务参数对象。

prompt string 必填

矢量画面描述：主体、形状、风格和需要出现的文字。1–10000 个字符。

image_size enum 可选

画布比例预设。预设只决定画布方向与比例，输出 SVG 可无损缩放到任意尺寸。

默认 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。

r integer 必填

0–255，红

g integer 必填

0–255，绿

b integer 必填

0–255，蓝

callback object 可选

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

url string 必填

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

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

when enum 可选

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

默认 final 可选值: final

用例示例

指定品牌配色

colors 指定深绿与沙色，background_color 指定米白；输出 SVG 里的路径会落在这组配色中。

请求体

{
  "model": "recraft-v4-pro/text-to-vector",
  "input": {
    "prompt": "A minimal geometric mountain mark for an outdoor brand, flat vector, centered",
    "image_size": "square_hd",
    "colors": [
      {
        "r": 22,
        "g": 61,
        "b": 52
      },
      {
        "r": 232,
        "g": 212,
        "b": 178
      }
    ],
    "background_color": {
      "r": 250,
      "g": 246,
      "b": 238
    }
  }
}

获取结果

提交成功后立即返回 taskId（不等待生成完成）。
生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
status=success 后，从返回的 output[].url 下载 SVG 文件。
下载后可用浏览器、Figma、Illustrator 或 Sketch 打开；SVG 是文本格式的矢量文件。
如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

Pro 档适合什么任务？

直接交付的 Logo、复杂图标组和细节丰富的矢量插画，以及需要统一视觉语言的品牌资产。

和普通 V4 Vector 有什么不同？

输入参数一致。Pro 会更认真地处理轮廓、层次和小结构，输出更接近成品；V4 更适合快速方案和批量草图。

输出是什么格式？

可编辑的 SVG 矢量文件，一次请求返回一个文件，从任务结果的 output[].url 获取。

支持哪些画布尺寸？

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

可以指定品牌色吗？

可以。传 colors（RGB 对象数组）和 background_color（单个 RGB 对象），每个通道 0–255。

生成的文件能进设计工具吗？

可以。SVG 支持 Figma、Illustrator、Sketch 等工具，后续可改节点、颜色、文字和导出尺寸。

需要上传参考图吗？