SOUL Cinema — Text to image API

← SOUL Cinema Endpoint: POST https://api.higgsfield.ai/higgsfield-ai/soul/cinema Endpoint ID: higgsfield-ai/soul/cinema ▶Open API PlaygroundSOUL Cinema · Text to image↗

Usage notes

batch_size is 1 or 4 only. A custom_reference_id must belong to the calling account and have completed training.
aspect_ratio defaults to 1:1 and enhance_prompt defaults to false. seed defaults to a random integer from 1 to 1000000; explicit null is invalid.
Providing a custom_reference_id enables prompt enhancement for the character reference, even if enhance_prompt is false.
Cinema uses a fixed style; client-supplied style_id is ignored.
This model may be absent from model discovery; authorized requests can use the endpoint ID directly.

Quick start

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" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --data '{
  "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
  "resolution": "720p",
  "aspect_ratio": "1:1",
  "enhance_prompt": true,
  "batch_size": 1
}'

import higgsfield_client

arguments = (
    {'prompt': 'A ceramic vase on a wooden table beside a sunlit window, soft '
               'natural shadows, editorial photograph.',
     'resolution': '720p',
     'aspect_ratio': '1:1',
     'enhance_prompt': True,
     'batch_size': 1}
)
result = higgsfield_client.subscribe(
    "higgsfield-ai/soul/cinema",
    arguments=arguments,
)
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/cinema", {
  input:
    {
      "prompt": "A ceramic vase on a wooden table beside a sunlit window, soft natural shadows, editorial photograph.",
      "resolution": "720p",
      "aspect_ratio": "1:1",
      "enhance_prompt": true,
      "batch_size": 1
    },
  withPolling: true,
});

if (result.status === "completed") {
  console.log(result.images?.[0]?.url);
}

Input schema

string

required

Text instructions for the generation or edit.

string

default:"1:1"

Output width-to-height ratio. Allowed values: "9:16", "16:9", "4:3", "3:4", "1:1", "2:3", "3:2".

boolean

default:"false"

Enable prompt enhancement. Providing custom_reference_id enables enhancement even when this field is false.

string

default:"720p"

Output resolution tier. Allowed values: "720p", "1080p".

string | null

Identifier of a completed character reference owned by your account. Format: uuid. Omit this field to use the server default; null is accepted only when included in the field type.

number

default:"1.0"

Strength of the character reference. Minimum: 0. Maximum: 1.

integer

Seed used to control generation randomness. Minimum: 1. Maximum: 1000000.

integer

default:"1"

Number of output images. Allowed values: 1, 4.

Complete JSON schema

{
  "properties": {
    "prompt": {
      "title": "Prompt",
      "type": "string"
    },
    "aspect_ratio": {
      "default": "1:1",
      "enum": [
        "9:16",
        "16:9",
        "4:3",
        "3:4",
        "1:1",
        "2:3",
        "3:2"
      ],
      "title": "Aspect Ratio",
      "type": "string"
    },
    "enhance_prompt": {
      "default": false,
      "title": "Enhance Prompt",
      "type": "boolean"
    },
    "resolution": {
      "default": "720p",
      "enum": [
        "720p",
        "1080p"
      ],
      "title": "Resolution",
      "type": "string"
    },
    "custom_reference_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Custom Reference Id"
    },
    "custom_reference_strength": {
      "default": 1.0,
      "maximum": 1,
      "minimum": 0,
      "title": "Custom Reference Strength",
      "type": "number"
    },
    "seed": {
      "maximum": 1000000,
      "minimum": 1,
      "title": "Seed",
      "type": "integer"
    },
    "batch_size": {
      "default": 1,
      "enum": [
        1,
        4
      ],
      "title": "Batch Size",
      "type": "integer"
    }
  },
  "required": [
    "prompt"
  ],
  "title": "SoulCinemaParamsSchema",
  "type": "object"
}

Response

Submission returns a request handle. Poll status_url until status is completed, or use webhooks.

Accepted

{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}

A completed response includes the following output fields:

{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "images": [
    {
      "url": "https://example.com/output.png"
    }
  ]
}

See idempotent requests, polling, request errors and authentication for shared request handling.

Requests

Models

SOUL Cinema — Text to image API

Usage notes

Quick start

Input schema

Response

​Usage notes

​Quick start

​Input schema

​Response

Usage notes

Quick start

Input schema

Response