# Recraft V4.1 Utility Pro

> Recraft V4.1 Utility Pro generates images from text prompts with customizable resolution, aspect ratio, output format, and color options. Users can specify background colors and a palette of colors to influence the image creation process.

## Overview

- **Endpoint**: `https://api.higgsfield.ai/recraft/v4.1/utility/pro/text-to-image`
- **Model ID**: `recraft/v4.1/utility/pro/text-to-image`
- **Category**: text2image
- **Kind**: inference

## Pricing

Public pricing information is not available for this model.

## Authentication

Keep credentials in server-side environment variables. The SDKs accept the same `KEY_ID:KEY_SECRET` value under their documented variable names.

```bash
export HF_CREDENTIALS="YOUR_KEY_ID:YOUR_KEY_SECRET" # TypeScript
export HF_KEY="YOUR_KEY_ID:YOUR_KEY_SECRET"         # Python and cURL
```

The official SDKs configure the authorization header. Keep credentials server-side; the TypeScript SDK blocks browser use.

## API Information

Use `subscribe` to submit the model request and wait for a terminal result. TypeScript performs automatic polling with `withPolling: true`; Python's synchronous `subscribe` call also waits.

### Input Parameters

- **`colors`** (`list<object>`, _optional_):

- **`prompt`** (`string`, _required_):
  Write your prompt here

- **`resolution`** (`string`, _optional_):
  - Default: `"2k"`
  - Options: `2k`

- **`aspect_ratio`** (`string`, _optional_):
  - Default: `"1:1"`
  - 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`, _optional_):
  - Default: `"jpg"`
  - Options: `jpg`, `png`, `webp`

- **`background_color`** (`object`, _optional_):

### Input JSON Schema

```json
{
  "type": "object",
  "title": "Recraft V4.1 Utility Pro Playground",
  "required": [
    "prompt"
  ],
  "properties": {
    "colors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "rgb"
        ],
        "properties": {
          "rgb": {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 255,
              "minimum": 0
            },
            "maxItems": 3,
            "minItems": 3
          }
        }
      },
      "title": "Colors"
    },
    "prompt": {
      "type": "string",
      "title": "Prompt",
      "maxLength": 10000,
      "minLength": 1,
      "description": "Write your prompt here"
    },
    "resolution": {
      "enum": [
        "2k"
      ],
      "type": "string",
      "title": "Resolution",
      "default": "2k"
    },
    "aspect_ratio": {
      "enum": [
        "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"
      ],
      "type": "string",
      "title": "Aspect ratio",
      "default": "1:1"
    },
    "output_format": {
      "enum": [
        "jpg",
        "png",
        "webp"
      ],
      "type": "string",
      "title": "Output format",
      "default": "jpg"
    },
    "background_color": {
      "type": "object",
      "title": "Background color",
      "required": [
        "rgb"
      ],
      "properties": {
        "rgb": {
          "type": "array",
          "items": {
            "type": "integer",
            "maximum": 255,
            "minimum": 0
          },
          "maxItems": 3,
          "minItems": 3
        }
      }
    }
  },
  "additionalProperties": false
}
```

### Required Parameters Example

```json
{
  "prompt": "A cinematic scene at sunset",
  "resolution": "2k",
  "aspect_ratio": "1:1",
  "output_format": "jpg"
}
```

### Output Schema

The shared polling endpoint returns one of the following status shapes:

```json
{
  "title": "RequestStatus",
  "oneOf": [
    {
      "title": "PendingRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "in_progress",
            "nsfw",
            "canceled"
          ]
        }
      },
      "required": [
        "status",
        "request_id"
      ]
    },
    {
      "title": "FailedRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "const": "failed"
        },
        "error": {
          "type": "string"
        }
      },
      "required": [
        "status",
        "request_id",
        "error"
      ]
    },
    {
      "title": "CompletedRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "const": "completed"
        },
        "images": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "url"
            ]
          }
        }
      },
      "required": [
        "status",
        "request_id",
        "images"
      ]
    }
  ]
}
```

## SDK Installation

Install one of the official server-side SDKs:

```bash
npm install @higgsfield/client
# or
pip install higgsfield-client
```

## Usage Examples

### TypeScript

```typescript
import { config, higgsfield } from "@higgsfield/client/v2";

config({
  credentials: process.env.HF_CREDENTIALS,
});

const result = await higgsfield.subscribe(
  "recraft/v4.1/utility/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);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'recraft/v4.1/utility/pro/text-to-image',
    arguments={'prompt': 'A cinematic scene at sunset',
         'resolution': '2k',
         'aspect_ratio': '1:1',
         'output_format': 'jpg'},
)

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/recraft/v4.1/utility/pro/text-to-image' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "A cinematic scene at sunset",
  "resolution": "2k",
  "aspect_ratio": "1:1",
  "output_format": "jpg"
}
JSON
```

## Additional Documentation

# About

**Recraft V4.1 Utility Pro** uses the model ID `recraft/v4.1/utility/pro/text-to-image`. Recraft V4.1 Utility Pro generates images from text prompts with customizable resolution, aspect ratio, output format, and color options. Users can specify background colors and a palette of colors to influence the image creation process.

## 1. Calling the API

Send requests to `https://api.higgsfield.ai/recraft/v4.1/utility/pro/text-to-image` with a JSON body matching the parameters below.

### Install

Install an official server-side SDK. cURL needs no package.

```bash control=package group=install-typescript variant=npm label=npm when=javascript
npm install @higgsfield/client
```

```bash control=package group=install-python variant=pip label=pip when=python
pip install higgsfield-client
```

### Setup

Keep credentials in server-side environment variables. The SDKs accept the same `KEY_ID:KEY_SECRET` value under their documented variable names.

```bash
export HF_CREDENTIALS="YOUR_KEY_ID:YOUR_KEY_SECRET" # TypeScript
export HF_KEY="YOUR_KEY_ID:YOUR_KEY_SECRET"         # Python and cURL
```

### Request 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:

```http
Authorization: Key $HF_KEY
```

## 3. 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

```ts control=language group=submit variant=javascript label=TypeScript
import { config, higgsfield } from "@higgsfield/client/v2";

config({
  credentials: process.env.HF_CREDENTIALS,
});

const result = await higgsfield.subscribe(
  "recraft/v4.1/utility/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);
```

```python control=language group=submit variant=python label=Python
import higgsfield_client

result = higgsfield_client.subscribe(
    'recraft/v4.1/utility/pro/text-to-image',
    arguments={'prompt': 'A cinematic scene at sunset',
         'resolution': '2k',
         'aspect_ratio': '1:1',
         'output_format': 'jpg'},
)

print(result)
```

```bash control=language group=submit variant=curl label=cURL
curl --request POST \
  --url 'https://api.higgsfield.ai/recraft/v4.1/utility/pro/text-to-image' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "A cinematic scene at sunset",
  "resolution": "2k",
  "aspect_ratio": "1:1",
  "output_format": "jpg"
}
JSON
```

### 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`.

```python
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)
```

## Additional Resources

- [Model page](https://console.higgsfield.ai/models/recraft/v4.1/utility/pro/text-to-image)
- [This LLM-readable document](https://dash.higgsfield.ai/models/recraft/v4.1/utility/pro/text-to-image/llms.txt)