Recraft V4 Vector API

Q: 需要上传参考图吗？

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

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

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

模型概览

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

Recraft V4 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/text-to-vector",
  "input": {
    "prompt": "A geometric vector logo for an outdoor brand called \"FOXPEAK\": a mountain fox head built from simple triangles, deep green and warm sand palette, centered on a cream background, flat design, thick clean edges, no gradients, no shadows",
    "image_size": "square_hd"
  }
}'

import requests, json

# 业务参数对象，字段随模型而定（见对应模型页）
payload = json.loads(r'''
{
  "model": "recraft-v4/text-to-vector",
  "input": {
    "prompt": "A geometric vector logo for an outdoor brand called \"FOXPEAK\": a mountain fox head built from simple triangles, deep green and warm sand palette, centered on a cream background, flat design, thick clean edges, no gradients, no shadows",
    "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/text-to-vector",
  "input": {
    "prompt": "A geometric vector logo for an outdoor brand called \"FOXPEAK\": a mountain fox head built from simple triangles, deep green and warm sand palette, centered on a cream background, flat design, thick clean edges, no gradients, no shadows",
    "image_size": "square_hd"
  }
}),
});
console.log(await resp.json()); // 成功返回 { code, message, data: { taskId } }

model string 必填

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

示例 recraft-v4/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/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，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

输出是什么格式？

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

和 Recraft V4 Pro Vector 有什么区别？

两者输入参数一致。V4 Vector 更快、成本更低，适合批量方案和简单图形；Pro 更注重细节和完成度。

支持哪些画布尺寸？

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

怎么指定配色？

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

需要上传参考图吗？