Recraft V4 Styles API

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

Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name	recraft-v4-styles/text-to-image
Type	Image generation (style-reference text-to-image)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

Recraft V4 Styles: set a style with 1–10 reference images, then describe a scene to get a new image in that style, one per request.

Production guidance

For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
To keep a set of images in one style, send the same image_urls with every request.
Result URLs expire — copy the output to your own storage once the task succeeds.

Best suited for

Illustration series

One set of references with different prompts gives a consistent set of images.

image_urlsprompt

Extending a brand look

Use existing brand illustrations as references and pin brand colors with colors when needed.

image_urlscolors

Multiple placements

Use portrait or landscape presets for different placements.

image_size

Request parameters

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

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account 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-styles/text-to-image",
  "input": {
    "prompt": "A cozy corner café on a rainy street at dusk, a cat sitting in the window, no logos, no brand names",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/1d68aea559e20871.png",
      "https://static.hiapi.ai/gallery/2026/10/01be0ab874ba475e.png"
    ],
    "image_size": "square_hd"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "recraft-v4-styles/text-to-image",
  "input": {
    "prompt": "A cozy corner café on a rainy street at dusk, a cat sitting in the window, no logos, no brand names",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/1d68aea559e20871.png",
      "https://static.hiapi.ai/gallery/2026/10/01be0ab874ba475e.png"
    ],
    "image_size": "square_hd"
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account 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-styles/text-to-image",
  "input": {
    "prompt": "A cozy corner café on a rainy street at dusk, a cat sitting in the window, no logos, no brand names",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/1d68aea559e20871.png",
      "https://static.hiapi.ai/gallery/2026/10/01be0ab874ba475e.png"
    ],
    "image_size": "square_hd"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Fixed value recraft-v4-styles/text-to-image.

example recraft-v4-styles/text-to-image

input object required

Business parameters.

prompt string required

What to draw, 1–10000 characters. The style comes from image_urls.

image_urls array required

1–10 publicly accessible http(s) URLs of style reference images. PNG, JPG or WEBP, each under 20 MB and 64 MB in total; SVG is not supported.

image_size enum optional

Output size preset.

default square_hd enum: square_hdsquareportrait_4_3portrait_16_9landscape_4_3landscape_16_9

style_match enum optional

How closely to follow the reference style: precise stays closer, flexible allows more variation; behaves as flexible when omitted.

enum: flexibleprecise

colors array optional

Optional preferred palette as an array of RGB objects.

r integer required

0–255, red

g integer required

0–255, green

b integer required

0–255, blue

background_color object optional

Optional preferred background color as an RGB object; r, g and b from 0 to 255.

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

Two references and one prompt

Two flat orange-and-teal illustrations as references and a prompt for a rainy corner café; the 1024×1024 output keeps their palette and light.

Request body

{
  "model": "recraft-v4-styles/text-to-image",
  "input": {
    "prompt": "A cozy corner café on a rainy street at dusk, a cat sitting in the window, no logos, no brand names",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/1d68aea559e20871.png",
      "https://static.hiapi.ai/gallery/2026/10/01be0ab874ba475e.png"
    ],
    "image_size": "square_hd"
  }
}

Getting the result

The response returns a taskId immediately without waiting for generation to finish.
In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
When status=success, download the image from output[].url.
When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

Are reference images required?

Yes. image_urls takes at least 1 and up to 10 images.

What can the reference images be?

Publicly accessible http(s) URLs of PNG, JPG or WEBP images, each under 20 MB and 64 MB in total; SVG is not supported.

How do I choose style_match?

precise stays closer to the reference style, flexible allows more variation; it behaves as flexible when omitted.

Which sizes are supported?

image_size accepts square_hd (default), square, portrait_4_3, portrait_16_9, landscape_4_3 and landscape_16_9. The square_hd example came back at 1024×1024.

Can I set the palette?

Yes, through the API with colors (an array of RGB objects) and background_color (one RGB object). The online Playground does not show these two fields yet.

Can I reuse a saved style?

Saved styles cannot be passed in at the moment; send the reference images with every request.

How many images per request?

One image per request, downloaded from output[].url in the task result.