Cinema Studio 4.0 — Generate API

← Cinema Studio 4.0 Endpoint: POST https://api.higgsfield.ai/higgsfield/cinema-studio/4.0 Endpoint ID: higgsfield/cinema-studio/4.0 ▶Open API PlaygroundCinema Studio 4.0 · Generate↗

Usage notes

This is the public Cinema Studio 4.0 workflow. It uses text-to-video when references are absent and reference-to-video when any media array is nonempty.
Omit creative-control fields to let the director choose them automatically; the literal value “auto” is not accepted for these enum fields.
Optional prompt references use one-based tokens such as <<<image_1>>>, <<<video_1>>> and <<<audio_1>>>. Each token must refer to an attached item of the same media type.
This endpoint produces a new video. Editing and extension use the separate Seedance 2.5 endpoints.
Reference media are limited to 30 images, 10 videos and 10 audio files, with at most 50 items total. Video and audio may be normalized to separate 30-second total budgets.

Quick start

curl --request POST \
  --url https://api.higgsfield.ai/higgsfield/cinema-studio/4.0 \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
  "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement."
}'

import higgsfield_client

arguments = (
    {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
               'movement.'}
)
result = higgsfield_client.subscribe(
    "higgsfield/cinema-studio/4.0",
    arguments=arguments,
)
print(result["video"]["url"])

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 wide shot of ocean waves at sunset, with gentle camera movement."
    },
  withPolling: true,
});

if (result.status === "completed") {
  console.log(result.video?.url);
}

Input schema

string

Allowed values: "1960s", "1980s", "1990s", "2000s", "2020s".

string

Allowed values: "epic", "drama", "noir", "comedy", "horror", "action".

string

Allowed values: "silhouette", "practicals", "window", "overhead-fall", "contre-jour", "soft-cross".

string

Allowed values: "chaotic", "dynamic", "calm", "single-shot".

string

required

Text instructions for the generation or edit. Minimum characters: 1. Pattern: \S.

integer

default:"5"

Requested output duration in seconds. Minimum: 4. Maximum: 30.

array

Ordered public audio reference URLs. Maximum items: 10. Each item: string. Format: uri.

array

Ordered public image reference URLs. Maximum items: 30. Each item: string. Format: uri.

string

default:"720p"

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

array

Ordered public video reference URLs. Maximum items: 10. Each item: string. Format: uri.

string

Allowed values: "clean-sharp", "anamorphic", "vintage-anamorphic", "warm-vintage", "halation-vintage".

string

default:"16:9"

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

string

Allowed values: "modern", "35mm-film", "8mm-film", "dv-camcorder".

string

Allowed values: "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".

boolean

default:"true"

Generate audio with the video.

string

Allowed values: "f14-wide-open", "f4-moderate", "f11-deep-focus".

string

Allowed values: "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".

Complete JSON schema

{
  "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
}

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",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}

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

Get started

Model API reference

Core concepts

SDKs

Organizations

API reference

Resources

Cinema Studio 4.0 — Generate API

Usage notes

Quick start

Input schema

Response

​Usage notes

​Quick start

​Input schema

​Response

Usage notes

Quick start

Input schema

Response