> ## Documentation Index
> Fetch the complete documentation index at: https://docs.higgsfield.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SOUL Text to Image API

> Generate stylized prompt-led images with SOUL.

<div className="models-color-scope" aria-hidden="true" />

<div className="model-workflow-tabs" aria-label="SOUL endpoints">
  <a className="model-workflow-tab is-active" href="/docs/models/soul-standard/generate">Text to image</a>
</div>

**Endpoint:** `POST https://api.higgsfield.ai/higgsfield-ai/soul/standard`

**Endpoint ID:** `higgsfield-ai/soul/standard`

<a className="model-playground-card" href="https://console.higgsfield.ai/models/higgsfield-ai%2Fsoul%2Fstandard/playground" target="_blank" rel="noreferrer">
  <span className="model-playground-icon">▶</span>
  <span className="model-playground-copy"><span className="model-playground-title">Try SOUL</span><span>Open this endpoint in the Higgsfield API Playground.</span></span>
  <span className="model-card-arrow">↗</span>
</a>

## Quick Start

<CodeGroup>
  ```python Python theme={"dark"}
  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"])
  ```

  ```typescript TypeScript theme={"dark"}
  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);
  ```

  ```bash cURL theme={"dark"}
  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
    }'
  ```
</CodeGroup>

## Input Schema

<ParamField body="prompt" type="string" required>
  Text description of the image to generate.
</ParamField>

<ParamField body="aspect_ratio" type="string" default="4:3">
  Supported values: `9:16`, `16:9`, `4:3`, `3:4`, `1:1`, `2:3`, `3:2`.
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  Supported values: `720p`, `1080p`.
</ParamField>

<ParamField body="style_id" type="string">
  SOUL style UUID returned by the [SOUL styles endpoint](#list-soul-styles). Omit this field to use the default General style.
</ParamField>

<ParamField body="style_strength" type="number" default="1">
  Strength of the selected style from `0` to `1`.
</ParamField>

<ParamField body="batch_size" type="integer" default="1">
  Number of images to generate. Supported values: `1`, `4`.
</ParamField>

<ParamField body="enhance_prompt" type="boolean" default="true">
  Enhance the prompt using the selected SOUL style before image generation.
</ParamField>

<ParamField body="seed" type="integer">
  Seed from `1` to `1000000`. Omit it to generate a random seed.
</ParamField>

## List SOUL styles

`GET https://api.higgsfield.ai/v1/text2image/soul-styles`

Use this authenticated endpoint to retrieve valid `style_id` values.

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

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

## Output Schema

<ResponseField name="status" type="string" required>
  Request state. A newly accepted request returns `queued`.
</ResponseField>

<ResponseField name="request_id" type="string" required>
  Stable identifier used for polling, cancellation, and support.
</ResponseField>

<ResponseField name="status_url" type="string" required>
  URL to poll until the request reaches a terminal state.
</ResponseField>

<ResponseField name="cancel_url" type="string" required>
  URL used to cancel a request before processing starts.
</ResponseField>

<ResponseField name="images" type="array">
  Completed image outputs. The array contains one or four items according to `batch_size`; each item contains a download `url`.
</ResponseField>

## Input Examples

Replace `<style-uuid>` with an `id` returned by [List SOUL styles](#list-soul-styles) before submitting the selected-style example.

<CodeGroup>
  ```json General style theme={"dark"}
  {
    "prompt": "Graphic fashion portrait with sculptural shadows and a cobalt backdrop",
    "aspect_ratio": "4:3",
    "resolution": "1080p",
    "enhance_prompt": true,
    "batch_size": 1
  }
  ```

  ```json Selected style theme={"dark"}
  {
    "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
  }
  ```
</CodeGroup>

## Output Example

<CodeGroup>
  ```json Accepted theme={"dark"}
  {
    "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"
  }
  ```

  ```json Completed theme={"dark"}
  {
    "status": "completed",
    "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
    "images": [{ "url": "https://cdn.example.com/soul-standard-output.jpg" }]
  }
  ```
</CodeGroup>

<Tip>
  Use an SDK for automatic polling, or poll the returned [status URL](/docs/concepts/polling).
</Tip>


## Related topics

- [SOUL 2 Text to Image API](/docs/models/soul-2/generate.md)
- [SOUL Cinema Text to Image API](/docs/models/soul-cinema/generate.md)
- [Recraft V4.1 Pro Text to Image API](/docs/models/recraft-v4-1-pro/generate.md)
- [SOUL API](/docs/models/soul-standard.md)
- [SOUL 2 API](/docs/models/soul-2.md)