Recraft V4.1 Pro uses the model ID recraft/v4.1/pro/text-to-image. Recraft V4.1 Pro generates images from text prompts with customizable resolution, aspect ratio, output format, and color options. Users can specify background and palette colors to tailor the visual style of the output.
1. Calling the API
Send requests to https://api.higgsfield.ai/recraft/v4.1/pro/text-to-image with a JSON body matching the parameters below.
Install
Install an official server-side SDK. cURL needs no package.
npm install @higgsfield/clientSetup
Keep credentials in server-side environment variables. The SDKs accept the same KEY_ID:KEY_SECRET value under their documented variable names.
export HF_CREDENTIALS="YOUR_KEY_ID:YOUR_KEY_SECRET" # TypeScript
export HF_KEY="YOUR_KEY_ID:YOUR_KEY_SECRET" # Python and cURLRequest parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
colors | array[object] | No | — | Colors. |
prompt | string | Yes | — | Prompt. Minimum length: 1. Maximum length: 10000. |
resolution | string | No | "2k" | Resolution. Options: 2k. |
aspect_ratio | string | No | "1:1" | Aspect ratio. Options: 1:1, 2:1, 1:2, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 6:10, 14:10, 10:14, 16:9, 9:16. |
output_format | string | No | "jpg" | Output format. Options: jpg, png, webp. |
background_color | object | No | — | Background color. |
2. Authentication
The official SDKs read credentials from the server environment and send the required Authorization: Key KEY_ID:KEY_SECRET header.
API Key
Never expose the secret in browser-side code or commit it to source control. The TypeScript SDK is server-side only. For direct HTTP calls, use:
Authorization: Key $HF_KEY3. Queue
subscribe submits the asynchronous request and waits for a terminal result. The TypeScript SDK polls automatically when withPolling: true; the Python SDK's synchronous subscribe call also waits. A completed request returns generated files in the images array.
Submit and wait
import { config, higgsfield } from "@higgsfield/client/v2";
config({
credentials: process.env.HF_CREDENTIALS,
});
const result = await higgsfield.subscribe(
"recraft/v4.1/pro/text-to-image",
{
input: {
"prompt": "A cinematic scene at sunset",
"resolution": "2k",
"aspect_ratio": "1:1",
"output_format": "jpg"
},
withPolling: true,
},
);
console.log(result);Explicit lifecycle control
Use the Python SDK when a worker needs explicit status, result, or cancellation control for an existing request. The TypeScript v2 client currently exposes automatic polling through subscribe.
import higgsfield_client
request_id = "{request_id}"
status = higgsfield_client.status(request_id=request_id)
result = higgsfield_client.result(request_id=request_id)
higgsfield_client.cancel(request_id=request_id)