# Cinema Studio 4.0

> Generates cinematic videos up to 30 seconds with automatic scene direction.

## Overview

- **Endpoint**: `https://api.higgsfield.ai/higgsfield/cinema-studio/4.0`
- **Model ID**: `higgsfield/cinema-studio/4.0`
- **Category**: video2video
- **Kind**: inference
- **Tags**: featured, trending

## Pricing

Token-metered pricing. Billable video tokens = ceil((input video seconds + generated video seconds) × output width × output height × 24 fps / 1024). Image and audio references do not count as video input. At 480p or 720p, each 1,000 video tokens cost $0.0214 without video input or $0.01284 with video input (0.6× the standard rate). With video references, both input and generated video durations are billable. Rates shown are before any applicable customer discount.

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

- **`era`** (`string`, _optional_):
  - Options: `1960s`, `1980s`, `1990s`, `2000s`, `2020s`

- **`genre`** (`string`, _optional_):
  - Options: `epic`, `drama`, `noir`, `comedy`, `horror`, `action`

- **`light`** (`string`, _optional_):
  - Options: `silhouette`, `practicals`, `window`, `overhead-fall`, `contre-jour`, `soft-cross`

- **`pacing`** (`string`, _optional_):
  - Options: `chaotic`, `dynamic`, `calm`, `single-shot`

- **`prompt`** (`string`, _required_):

- **`duration`** (`integer`, _optional_):
  - Default: `5`

- **`audio_urls`** (`list<string>`, _optional_):

- **`image_urls`** (`list<string>`, _optional_):

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

- **`video_urls`** (`list<string>`, _optional_):

- **`camera_lens`** (`string`, _optional_):
  - Options: `clean-sharp`, `anamorphic`, `vintage-anamorphic`, `warm-vintage`, `halation-vintage`

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

- **`camera_model`** (`string`, _optional_):
  - Options: `modern`, `35mm-film`, `8mm-film`, `dv-camcorder`

- **`color_palette`** (`string`, _optional_):
  - Options: `static-noon`, `twilight-fable`, `back-row-kissing-seats`, `on-the-other-side-of-the-porthole`, `the-emerald-ambush`, `highway-standoff`, `the-faded-fresco`, `oil-ochre`, `the-mountain-convent`, `ghost-in-the-code`, `pink-velvet`, `two-days-to-the-horizon`, `industrial-fog`, `stairs-go-up`, `field-post`, `home-is-the-next-gas-station`, `glossy-flesh`, `the-crimson-ballet`, `neon-rain-at-midnight`, `the-morning-after-rain`, `the-iron-borough`, `the-ground`, `the-investigation`, `turquoise-mirage`, `a-dream-in-color`, `breakfast-on-schedule`, `favela-gold`, `a-hotel-for-one`, `after-dark`, `crimson-vigi`, `the-neighbors-saw-everything`, `the-grey-channel`, `mirage-at-noon`, `bubblegum-boulevard`, `yellow-room`, `the-earth-keeps-things-reluctantly`, `tropic-fever-dream`, `bioluminescent-night`, `dont-turn-it-off-im-watching`, `the-silk-curtain-falls`, `the-butterfly`, `playtime`, `wallpaper-romance`, `overtime`, `the-way-home-is-longer`, `everyone-speaks-in-whispers`, `runaway-summer`, `amber-wasteland`, `the-circus`, `gasoline-sunset`

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

- **`camera_aperture`** (`string`, _optional_):
  - Options: `f14-wide-open`, `f4-moderate`, `f11-deep-focus`

- **`camera_movement`** (`string`, _optional_):
  - Options: `snorricam`, `robot-arm`, `tilt-up`, `rack-focus`, `tilt-down`, `pov`, `pan-left`, `crane-up`, `pan-right`, `crane-down`, `side-tracking`, `pedestal-up`, `pedestal-down`, `handheld`, `tracking`, `drone-orbit`, `dolly-zoom`, `aerial-pullback`, `static-shot`, `bullet-time`, `whip-pan`, `slow-zoom-in`, `arc-left`, `slow-zoom-out`, `arc-right`, `truck-right`, `dolly-in`, `truck-left`, `dolly-out`, `slider-right`, `crush-zoom`, `slider-left`, `helicopter-shot`

### Input JSON Schema

```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "era": {
      "enum": [
        "1960s",
        "1980s",
        "1990s",
        "2000s",
        "2020s"
      ],
      "type": "string"
    },
    "genre": {
      "enum": [
        "epic",
        "drama",
        "noir",
        "comedy",
        "horror",
        "action"
      ],
      "type": "string"
    },
    "light": {
      "enum": [
        "silhouette",
        "practicals",
        "window",
        "overhead-fall",
        "contre-jour",
        "soft-cross"
      ],
      "type": "string"
    },
    "pacing": {
      "enum": [
        "chaotic",
        "dynamic",
        "calm",
        "single-shot"
      ],
      "type": "string"
    },
    "prompt": {
      "type": "string",
      "pattern": "\\S",
      "minLength": 1
    },
    "duration": {
      "type": "integer",
      "default": 5,
      "maximum": 30,
      "minimum": 4
    },
    "audio_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "maxItems": 10
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "maxItems": 30
    },
    "resolution": {
      "enum": [
        "480p",
        "720p"
      ],
      "type": "string",
      "default": "720p"
    },
    "video_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "maxItems": 10
    },
    "camera_lens": {
      "enum": [
        "clean-sharp",
        "anamorphic",
        "vintage-anamorphic",
        "warm-vintage",
        "halation-vintage"
      ],
      "type": "string"
    },
    "aspect_ratio": {
      "enum": [
        "16:9",
        "4:3",
        "1:1",
        "3:4",
        "9:16",
        "21:9"
      ],
      "type": "string",
      "default": "16:9"
    },
    "camera_model": {
      "enum": [
        "modern",
        "35mm-film",
        "8mm-film",
        "dv-camcorder"
      ],
      "type": "string"
    },
    "color_palette": {
      "enum": [
        "static-noon",
        "twilight-fable",
        "back-row-kissing-seats",
        "on-the-other-side-of-the-porthole",
        "the-emerald-ambush",
        "highway-standoff",
        "the-faded-fresco",
        "oil-ochre",
        "the-mountain-convent",
        "ghost-in-the-code",
        "pink-velvet",
        "two-days-to-the-horizon",
        "industrial-fog",
        "stairs-go-up",
        "field-post",
        "home-is-the-next-gas-station",
        "glossy-flesh",
        "the-crimson-ballet",
        "neon-rain-at-midnight",
        "the-morning-after-rain",
        "the-iron-borough",
        "the-ground",
        "the-investigation",
        "turquoise-mirage",
        "a-dream-in-color",
        "breakfast-on-schedule",
        "favela-gold",
        "a-hotel-for-one",
        "after-dark",
        "crimson-vigi",
        "the-neighbors-saw-everything",
        "the-grey-channel",
        "mirage-at-noon",
        "bubblegum-boulevard",
        "yellow-room",
        "the-earth-keeps-things-reluctantly",
        "tropic-fever-dream",
        "bioluminescent-night",
        "dont-turn-it-off-im-watching",
        "the-silk-curtain-falls",
        "the-butterfly",
        "playtime",
        "wallpaper-romance",
        "overtime",
        "the-way-home-is-longer",
        "everyone-speaks-in-whispers",
        "runaway-summer",
        "amber-wasteland",
        "the-circus",
        "gasoline-sunset"
      ],
      "type": "string"
    },
    "generate_audio": {
      "type": "boolean",
      "default": true
    },
    "camera_aperture": {
      "enum": [
        "f14-wide-open",
        "f4-moderate",
        "f11-deep-focus"
      ],
      "type": "string"
    },
    "camera_movement": {
      "enum": [
        "snorricam",
        "robot-arm",
        "tilt-up",
        "rack-focus",
        "tilt-down",
        "pov",
        "pan-left",
        "crane-up",
        "pan-right",
        "crane-down",
        "side-tracking",
        "pedestal-up",
        "pedestal-down",
        "handheld",
        "tracking",
        "drone-orbit",
        "dolly-zoom",
        "aerial-pullback",
        "static-shot",
        "bullet-time",
        "whip-pan",
        "slow-zoom-in",
        "arc-left",
        "slow-zoom-out",
        "arc-right",
        "truck-right",
        "dolly-in",
        "truck-left",
        "dolly-out",
        "slider-right",
        "crush-zoom",
        "slider-left",
        "helicopter-shot"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### Required Parameters Example

```json
{
  "prompt": "A cinematic scene at sunset",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true
}
```

### 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"
        },
        "video": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "zip": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "mov": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "jsx": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "fbx": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "ply": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        }
      },
      "required": [
        "status",
        "request_id",
        "video"
      ]
    }
  ]
}
```

## 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/cinema-studio/4.0",
  {
    input: {
      "prompt": "A cinematic scene at sunset",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    },
    withPolling: true,
  },
);

console.log(result);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'higgsfield/cinema-studio/4.0',
    arguments={'prompt': 'A cinematic scene at sunset',
         'duration': 5,
         'resolution': '720p',
         'aspect_ratio': '16:9',
         'generate_audio': True},
)

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/higgsfield/cinema-studio/4.0' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "A cinematic scene at sunset",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true
}
JSON
```

## Additional Resources

- [Model page](https://console.higgsfield.ai/models/higgsfield/cinema-studio/4.0)
- [This LLM-readable document](https://dash.higgsfield.ai/models/higgsfield/cinema-studio/4.0/llms.txt)