# Soul 2

> Generates realistic portraits and fashion images, with natural textures and curated editorial styles.

## Overview

- **Endpoint**: `https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard`
- **Model ID**: `higgsfield-ai/soul/v2/standard`
- **Category**: text2image
- **Kind**: inference
- **Tags**: featured, trending, inference, partners, commercial_use

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

- **`seed`** (`integer`, _optional_):
  - Default: `null`

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

- **`style_id`** (`string`, _optional_):

- **`batch_size`** (`integer`, _optional_):
  - Default: `1`
  - Options: `1`, `4`

- **`resolution`** (`string`, _optional_):
  - Default: `"720p"`
  - Options: `720p`, `1080p`

- **`aspect_ratio`** (`string`, _optional_):
  - Default: `"4:3"`
  - Options: `9:16`, `16:9`, `4:3`, `3:4`, `1:1`, `2:3`, `3:2`

- **`enhance_prompt`** (`boolean`, _optional_):
  - Default: `true`

- **`custom_reference_id`** (`['string', 'null']`, _optional_):
  ID of a completed Soul ID trained with model_version v2 in your API account. Create one using POST /v1/custom-references.
  - Default: `null`

- **`custom_reference_strength`** (`number`, _optional_):
  Strength of the custom reference, from 0 to 1. Used when custom_reference_id is provided.
  - Default: `1.0`

### Input JSON Schema

```json
{
  "type": "object",
  "title": "Soul V2 Playground",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer",
      "title": "Seed",
      "default": null,
      "maximum": 1000000,
      "minimum": 1
    },
    "prompt": {
      "type": "string",
      "title": "Prompt",
      "description": "Write your prompt here"
    },
    "style_id": {
      "type": "string",
      "title": "Soul Style",
      "format": "uuid"
    },
    "batch_size": {
      "enum": [
        1,
        4
      ],
      "type": "integer",
      "title": "Result images",
      "default": 1
    },
    "resolution": {
      "enum": [
        "720p",
        "1080p"
      ],
      "type": "string",
      "title": "Resolution",
      "default": "720p"
    },
    "aspect_ratio": {
      "enum": [
        "9:16",
        "16:9",
        "4:3",
        "3:4",
        "1:1",
        "2:3",
        "3:2"
      ],
      "type": "string",
      "title": "Aspect Ratio",
      "default": "4:3"
    },
    "enhance_prompt": {
      "type": "boolean",
      "title": "Enhance Prompt",
      "default": true
    },
    "custom_reference_id": {
      "type": [
        "string",
        "null"
      ],
      "title": "Soul ID",
      "format": "uuid",
      "default": null,
      "description": "ID of a completed Soul ID trained with model_version v2 in your API account. Create one using POST /v1/custom-references."
    },
    "custom_reference_strength": {
      "type": "number",
      "title": "Soul ID strength",
      "default": 1.0,
      "maximum": 1,
      "minimum": 0,
      "description": "Strength of the custom reference, from 0 to 1. Used when custom_reference_id is provided."
    }
  }
}
```

### Required Parameters Example

```json
{
  "seed": null,
  "prompt": "A cinematic scene at sunset",
  "batch_size": 1,
  "resolution": "720p",
  "aspect_ratio": "4:3",
  "enhance_prompt": true,
  "custom_reference_id": null,
  "custom_reference_strength": 1.0
}
```

### 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(
  "higgsfield-ai/soul/v2/standard",
  {
    input: {
      "seed": null,
      "prompt": "A cinematic scene at sunset",
      "batch_size": 1,
      "resolution": "720p",
      "aspect_ratio": "4:3",
      "enhance_prompt": true,
      "custom_reference_id": null,
      "custom_reference_strength": 1.0
    },
    withPolling: true,
  },
);

console.log(result);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'higgsfield-ai/soul/v2/standard',
    arguments={'seed': None,
         'prompt': 'A cinematic scene at sunset',
         'batch_size': 1,
         'resolution': '720p',
         'aspect_ratio': '4:3',
         'enhance_prompt': True,
         'custom_reference_id': None,
         'custom_reference_strength': 1.0},
)

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "seed": null,
  "prompt": "A cinematic scene at sunset",
  "batch_size": 1,
  "resolution": "720p",
  "aspect_ratio": "4:3",
  "enhance_prompt": true,
  "custom_reference_id": null,
  "custom_reference_strength": 1.0
}
JSON
```

## Additional Documentation

# About

**Soul 2** uses the model ID `higgsfield-ai/soul/v2/standard`. Soul V2 Standard generates images from text prompts with customizable style, resolution, aspect ratio, and batch size. Users can enhance prompts and set a seed for reproducibility, making it suitable for varied creative visual outputs.

## 1. Calling the API

Send requests to `https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard` 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 |
| --- | --- | --- | --- | --- |
| `seed` | `integer` | No | `null` | Seed. Minimum: 1. Maximum: 1000000. |
| `prompt` | `string` | Yes | `—` | Prompt. |
| `style_id` | `string` | No | `—` | Soul Style. |
| `custom_reference_id` | `string` (UUID) or `null` | No | `null` | Completed Soul ID trained for Soul 2 in the same API account. See Custom references below. |
| `custom_reference_strength` | `number` | No | `1.0` | Soul ID strength, from 0 to 1. Used with `custom_reference_id`. |
| `batch_size` | `integer` | No | `1` | Result images. Options: 1, 4. |
| `resolution` | `string` | No | `"720p"` | Resolution. Options: 720p, 1080p. |
| `aspect_ratio` | `string` | No | `"4:3"` | Aspect Ratio. Options: 9:16, 16:9, 4:3, 3:4, 1:1, 2:3, 3:2. |
| `enhance_prompt` | `boolean` | No | `true` | Enhance Prompt. |

## 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(
  "higgsfield-ai/soul/v2/standard",
  {
    input: {
      "prompt": "A cinematic scene at sunset",
      "batch_size": 1,
      "resolution": "720p",
      "aspect_ratio": "4:3",
      "enhance_prompt": true
    },
    withPolling: true,
  },
);

console.log(result);
```

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

result = higgsfield_client.subscribe(
    'higgsfield-ai/soul/v2/standard',
    arguments={'prompt': 'A cinematic scene at sunset',
         'batch_size': 1,
         'resolution': '720p',
         'aspect_ratio': '4:3',
         'enhance_prompt': True},
)

print(result)
```

```bash control=language group=submit variant=curl label=cURL
curl --request POST \
  --url 'https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "A cinematic scene at sunset",
  "batch_size": 1,
  "resolution": "720p",
  "aspect_ratio": "4:3",
  "enhance_prompt": true
}
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)
```

## 4. Custom references (Soul ID)

A [Soul ID](https://open.higgsfield.ai/models/soul-id/playground) is a trained custom reference that lets you reuse a person's identity in Soul 2 generations. Create it once, wait for training to finish, and pass its ID as `custom_reference_id`.

### Create a Soul ID for Soul 2

Send `POST /v1/custom-references` with a name, 1–100 input images, and **`model_version: "v2"`**. The default model version is `v1`, so explicitly select `v2` for Soul 2. Replace the example URLs with accessible images of the person you want to use.

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/v1/custom-references' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "name": "My Soul 2 character",
  "model_version": "v2",
  "input_images": [
    {"type": "image_url", "image_url": "https://example.com/portrait-1.jpg"},
    {"type": "image_url", "image_url": "https://example.com/portrait-2.jpg"}
  ]
}
JSON
```

Save the response's `id`. This is the Soul ID to use as `custom_reference_id`; it is not a generation `request_id`.

### Wait until the reference is ready

```bash
REFERENCE_ID="YOUR_SOUL_ID"
curl --request GET \
  --url "https://api.higgsfield.ai/v1/custom-references/${REFERENCE_ID}" \
  --header "Authorization: Key $HF_KEY"
```

Repeat the GET request at intervals until `status` is `completed`. If it is `failed`, training did not produce a usable reference. You can find existing Soul IDs with `GET /v1/custom-references/list?page=1&page_size=20`.

Use credentials belonging to the same API account for creation and generation. References belonging to another account, missing references, and references whose status is not `completed` cannot be used.

### Generate with your Soul ID

Replace `YOUR_COMPLETED_SOUL_ID` with the UUID returned when creating the reference. `custom_reference_strength` is optional, defaults to `1.0`, and accepts values from `0` to `1`.

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/higgsfield-ai/soul/v2/standard' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "A natural portrait of this person in soft window light",
  "custom_reference_id": "YOUR_COMPLETED_SOUL_ID",
  "custom_reference_strength": 1.0,
  "enhance_prompt": true,
  "resolution": "720p",
  "aspect_ratio": "1:1",
  "batch_size": 1
}
JSON
```

The generation response contains `request_id` and `status_url`. Poll `status_url` until completion and read the generated image URLs from `images`.

## Additional Resources

- [Model page](https://console.higgsfield.ai/models/higgsfield-ai/soul/v2/standard)
- [This LLM-readable document](https://dash.higgsfield.ai/models/higgsfield-ai/soul/v2/standard/llms.txt)