Recraft V4 Styles Text-to-Image API: curl, Python, and a Working Request

TL;DR

• recraft-v4-styles/text-to-image does not take a style_id. The style comes from 1–10 reference images in image_urls; the prompt only says what is in the picture.
• It runs on the unified async task API: POST /v1/tasks, poll GET /v1/tasks/<id>, read data.output[0].url.
• recraft-v4-styles-pro/text-to-image has the same parameters. According to the model pages it returns higher resolution (2048×2048 vs 1024×1024 at square_hd) at a higher price. I only ran the base tier myself (see below).

This guide shows how to call Recraft V4 Styles through hiapi when you want new images that match the look of existing ones: an illustration set, a brand palette, a watercolor series. You need a hiapi API key from the dashboard and one or more publicly reachable reference images (PNG, JPG or WEBP).

If you want prompt-only generation with Recraft, with no reference images, that is a different model: see the Recraft V4.1 API guide.

Minimal request (curl)

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft-v4-styles/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/model-covers/2026/10/23/1792724275412-ffdf43a59eb69dac-1792546242939-ffdf43a59eb69dac-style-ref-warm-interior.png",
        "https://static.hiapi.ai/model-covers/2026/10/23/1792726737526-bc31b881a76651e7-1792546244886-bc31b881a76651e7-style-ref-watercolor-harbor.png"
      ],
      "image_size": "square_hd"
    }
  }'

The response gives you a task id:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Poll it until data.status is success:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Input fields

One image comes back per request. The reference count, size preset and style_match do not change the price. This table comes from the model page; I only set prompt, image_urls and image_size in my own run.

Python version with polling

import os, time, requests

API = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(model, prompt, refs, size="square_hd"):
    r = requests.post(f"{API}/v1/tasks", headers=HEADERS, json={
        "model": f"{model}/text-to-image",
        "input": {"prompt": prompt, "image_urls": refs, "image_size": size},
    }, timeout=60)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:
        d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(5)

url = generate(
    "recraft-v4-styles",
    "A lighthouse on a cliff with seagulls and waves, no logos, no brand names",
    ["https://static.hiapi.ai/model-covers/2026/10/23/1792724275412-ffdf43a59eb69dac-1792546242939-ffdf43a59eb69dac-style-ref-warm-interior.png",
     "https://static.hiapi.ai/model-covers/2026/10/23/1792726737526-bc31b881a76651e7-1792546244886-bc31b881a76651e7-style-ref-watercolor-harbor.png"],
)
download = requests.get(url, timeout=60)
download.raise_for_status()
open("out.webp", "wb").write(download.content)

Switch to the Pro tier by passing "recraft-v4-styles-pro" as the first argument. Nothing else changes.

Production notes

• Download the result immediately. The output URL is on temp.hiapi.ai and carries an expireAt timestamp. In my run it was about seven days out. Copy the file to your own storage instead of hot-linking it.
• Treat a transient poll error as retryable. If one poll fails at the network level, re-poll the same taskId rather than submitting a new task, or you pay twice.
• Use a callback instead of polling for batch jobs. Add callback with url and when: "final" to the create request; see the docs.
• Keep your reference set fixed if you want a consistent series. Saved styles cannot be passed in right now, so you send the same references on every request.

What I actually ran

I called the base tier once with the two public style-reference images linked on the hiapi model pages (a warm interior and a watercolor harbor) and the lighthouse prompt above, at square_hd.

• Task creation returned a task id immediately. The task showed handling, then archiving, then success after roughly 30 seconds of generation.
• The output was a WebP file of 1024×1024, about 1.6 MB, matching the model page's statement for the base tier at square_hd.
• Validation is strict and useful. I sent an empty image_urls and image_size: "bogus" as a deliberate bad request. It came back as HTTP 400 INVALID_REQUEST and listed both problems in one message: image_urls: minItems: got 0, want 1 and the six valid image_size values. You get the full enum from the error, so no guessing.
• Ask for content in the prompt. The model page notes that objects in the references (a teapot, books) did not show up in the output; palette, shading and lighting carried over. Describe the subject you want, and do not expect the references to supply it.

Base vs Pro: what is and is not verified

I did not generate with the Pro tier. My Pro request was rejected with HTTP 402 INSUFFICIENT_QUOTA on the test account, so I have no side-by-side images and will not claim Pro looks better.

What I can verify from hiapi's own pages and the live pricing data:

• Same input schema for both tiers.
• Pro's example output on its model page is 2048×2048 at square_hd; the base tier's is 1024×1024.
• Pro is priced higher per image; as checked on October 26, 2026, it is roughly 2.6× the base price. Check pricing for current numbers.

A practical way to decide: prototype with the base tier, since a request is cheaper and the parameters are identical, and switch to Pro only when you need the larger file for print, posters or large brand assets. If 1024 px is enough for your use, the extra cost buys you nothing you asked for.

Related

• Recraft V4 Styles model page
• Recraft V4 Styles Pro model page
• Recraft V4.1 API guide (prompt-only, no style references)
• Recraft V4.1 API pricing
• hiapi pricing

FAQ

Is there a style_id parameter? No. The style is defined by the images you pass in image_urls, between 1 and 10.

How many reference images should I send? The API accepts 1 to 10. I tested with 2. I did not compare different counts, so I have no data on how the count affects the result.

Does the price depend on the number of references? No, per the model page it is per output image; reference count, size preset and style_match do not change it.

Can I reuse a saved style? Not currently. Send the same reference images with each request.

What if my reference URL is not public? The references need to be publicly reachable http(s) URLs. I did not test a private URL, so I can't say how the failure surfaces.