> ## 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 Cinema Text to Image API

> Generate cinematic stills with SOUL Cinema.

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

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

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

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

<a className="model-playground-card" href="https://console.higgsfield.ai/models/higgsfield-ai%2Fsoul%2Fcinema/playground" target="_blank" rel="noreferrer">
  <span className="model-playground-icon">▶</span>
  <span className="model-playground-copy"><span className="model-playground-title">Try SOUL Cinema</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/cinema",
      arguments={
          "prompt": "A lone astronaut crossing a monumental brutalist hall, volumetric light",
          "aspect_ratio": "16:9",
          "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/cinema",
    {
      input: {
        prompt: "A lone astronaut crossing a monumental brutalist hall, volumetric light",
        aspect_ratio: "16:9",
        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/cinema \
    --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
    --header "Content-Type: application/json" \
    --data '{
      "prompt": "A lone astronaut crossing a monumental brutalist hall, volumetric light",
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "enhance_prompt": true,
      "batch_size": 1
    }'
  ```
</CodeGroup>

## Input Schema

<ParamField body="prompt" type="string" required>
  Text description of the cinematic 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="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 supplied prompt for SOUL Cinema before generation.
</ParamField>

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

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

<CodeGroup>
  ```json Cinematic landscape theme={"dark"}
  {
    "prompt": "A coastal observatory above a storm, cinematic concept art",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "enhance_prompt": true,
    "batch_size": 1
  }
  ```

  ```json Reproducible batch theme={"dark"}
  {
    "prompt": "A futuristic couture portrait under a single hard spotlight",
    "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-cinema-output.jpg" }]
  }
  ```
</CodeGroup>

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


## Related topics

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