SOUL Text to Image API

Text to image

Endpoint: POST https://api.higgsfield.ai/higgsfield-ai/soul/standard Endpoint ID: higgsfield-ai/soul/standard ▶Try SOULOpen this endpoint in the Higgsfield API Playground.↗

Quick Start

import higgsfield_client

result = higgsfield_client.subscribe(
    "higgsfield-ai/soul/standard",
    arguments={
        "prompt": "Graphic fashion portrait with sculptural shadows and a cobalt backdrop",
        "aspect_ratio": "4:3",
        "resolution": "1080p",
        "enhance_prompt": True,
        "batch_size": 1,
    },
)

print(result["images"][0]["url"])

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

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

const result = await higgsfield.subscribe(
  "higgsfield-ai/soul/standard",
  {
    input: {
      prompt: "Graphic fashion portrait with sculptural shadows and a cobalt backdrop",
      aspect_ratio: "4:3",
      resolution: "1080p",
      enhance_prompt: true,
      batch_size: 1,
    },
    withPolling: true,
  },
);

if (result.isCompleted) console.log(result.jobs[0].results?.raw.url);

curl --request POST \
  --url https://api.higgsfield.ai/higgsfield-ai/soul/standard \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
    "prompt": "Graphic fashion portrait with sculptural shadows and a cobalt backdrop",
    "aspect_ratio": "4:3",
    "resolution": "1080p",
    "enhance_prompt": true,
    "batch_size": 1
  }'

Input Schema

string

required

Text description of the image to generate.

string

default:"4:3"

Supported values: 9:16, 16:9, 4:3, 3:4, 1:1, 2:3, 3:2.

string

default:"720p"

Supported values: 720p, 1080p.

string

SOUL style UUID returned by the SOUL styles endpoint. Omit this field to use the default General style.

number

default:"1"

Strength of the selected style from 0 to 1.

integer

default:"1"

Number of images to generate. Supported values: 1, 4.

boolean

default:"true"

Enhance the prompt using the selected SOUL style before image generation.

integer

Seed from 1 to 1000000. Omit it to generate a random seed.

List SOUL styles

GET https://api.higgsfield.ai/v1/text2image/soul-styles Use this authenticated endpoint to retrieve valid style_id values.

curl --request GET \
  --url https://api.higgsfield.ai/v1/text2image/soul-styles \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"

[
  {
    "id": "<style-uuid>",
    "name": "Editorial",
    "description": "A polished editorial image style.",
    "preview_url": "https://cdn.example.com/soul-style-preview.jpg"
  }
]

Output Schema

string

required

Request state. A newly accepted request returns queued.

string

required

Stable identifier used for polling, cancellation, and support.

string

required

URL to poll until the request reaches a terminal state.

string

required

URL used to cancel a request before processing starts.

array

Completed image outputs. The array contains one or four items according to batch_size; each item contains a download url.

Input Examples

Replace <style-uuid> with an id returned by List SOUL styles before submitting the selected-style example.

{
  "prompt": "Graphic fashion portrait with sculptural shadows and a cobalt backdrop",
  "aspect_ratio": "4:3",
  "resolution": "1080p",
  "enhance_prompt": true,
  "batch_size": 1
}

{
  "prompt": "Playful studio campaign with bold shapes and direct flash",
  "style_id": "<style-uuid>",
  "style_strength": 0.8,
  "aspect_ratio": "3:4",
  "resolution": "1080p",
  "enhance_prompt": true,
  "seed": 481516,
  "batch_size": 4
}

Output Example

{
  "status": "queued",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
  "cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
}

{
  "status": "completed",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "images": [{ "url": "https://cdn.example.com/soul-standard-output.jpg" }]
}

Use an SDK for automatic polling, or poll the returned status URL.

Get started

Model API reference

Core concepts

SDKs

Organizations

API reference

Resources

Quick Start

Input Schema

List SOUL styles

Output Schema

Input Examples

Output Example

​Quick Start

​Input Schema

​List SOUL styles

​Output Schema

​Input Examples

​Output Example

Quick Start

Input Schema

List SOUL styles

Output Schema

Input Examples

Output Example