---
canonical_url: "https://docs.composio.dev/toolkits/higgsfield"
markdown_url: "https://docs.composio.dev/toolkits/higgsfield.md"
product: "platform"
version: null
last_updated: null
---

# Higgsfield

Higgsfield AI provides asynchronous image and video generation APIs powered by multiple creative AI models.

- **Category:** media generation
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 12
- **Triggers:** 0
- **Slug:** `HIGGSFIELD`
- **Version:** 20261014_01
- **Instant:** Supported on the latest version. Support varies by tool.

## Tools

### Cancel Request

**Slug:** `HIGGSFIELD_CANCEL_REQUEST`

Cancel a Higgsfield generation request while it is still queued; requests already processing or finished cannot be canceled. Managed generation requests cannot be canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | Queued generation request ID returned by a generation action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Character Reference

**Slug:** `HIGGSFIELD_CREATE_CHARACTER_REFERENCE`

Start training a reusable Higgsfield Soul ID character reference from one or more public images. Poll GET_CHARACTER_REFERENCE with the returned ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Name of the character reference (maximum 100 characters). |
| `input_images` | array | Yes | One to 100 public images used to train the character reference. |
| `model_version` | string ("v1" | "v2" | "cinema") | No | SOUL model family that will use the character reference. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Estimate Soul V2 Cost

**Slug:** `HIGGSFIELD_ESTIMATE_SOUL_V2_COST`

Estimate the authenticated account's credit and USD cost for a fixed Higgsfield Soul V2 Standard image request without starting generation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `seed` | integer | No | Optional deterministic generation seed from 1 to 1000000. Omit it to let Higgsfield choose a random seed. |
| `prompt` | string | Yes | Text instructions for the image generation request to estimate. |
| `style_id` | string | No | Identifier of a style supported by Soul V2. |
| `batch_size` | integer ("1" | "4") | No | Number of output images. Soul V2 supports only 1 or 4. |
| `resolution` | string ("720p" | "1080p") | No | Output resolution tier. |
| `aspect_ratio` | string ("9:16" | "16:9" | "4:3" | "3:4" | "1:1" | "2:3" | "3:2") | No | Output width-to-height ratio. |
| `enhance_prompt` | boolean | No | Whether Higgsfield should enhance the prompt. |
| `style_strength` | number | No | Style strength from 0 to 1. Higgsfield currently accepts this field without applying it to generation. |
| `custom_reference_id` | string | No | Optional identifier of a completed character reference owned by the connected account. |
| `custom_reference_strength` | number | No | Character-reference strength from 0 to 1. When custom_reference_id is set, this must be greater than 0. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Content (Deprecated)

**Slug:** `HIGGSFIELD_GENERATE_CONTENT_BY_MODEL_ID`

Deprecated fallback for model routes without typed tools; returns a request ID for status polling. Prefer typed generation actions. Managed submissions charge the numeric provider estimate upfront, without refunds or cancellation after acceptance.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | The text prompt describing what to generate |
| `duration` | integer | No | Duration in seconds for video generation models |
| `model_id` | string ("reve/text-to-image") | Yes | Deprecated fallback model route not covered by a typed action. Existing legacy model IDs remain accepted for compatibility but are not advertised. |
| `image_url` | string | No | Public input image URL for image-to-video or image-to-image models |
| `resolution` | string | No | Provider-supported output resolution |
| `webhook_url` | string | No | Public HTTPS URL for notification when generation finishes |
| `aspect_ratio` | string | No | Aspect ratio for the output, such as 16:9, 1:1, 9:16, or 4:3 |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Image With References

**Slug:** `HIGGSFIELD_GENERATE_IMAGE_WITH_REFERENCES`

Submit a Higgsfield Popcorn request that uses one or more reference images and return the request ID used to track the asynchronous result. Managed estimates above $2 are rejected before generation submission. No polling is performed; use the returned request ID with GET_REQUEST_STATUS. Managed generation charges the numeric provider estimate when submission is accepted, including if generation later fails. Managed requests cannot be canceled.

**Instant:** Supported on the latest version.

**Instant pricing:** Popcorn Auto image generation uses the provider estimate for the reference images and selected output count and resolution, up to $2 per request.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `seed` | integer | No | Optional deterministic generation seed (1-1000000). |
| `prompt` | string | Yes | Text description of the image to generate using the references. |
| `image_urls` | array | Yes | Public URLs of 1-8 reference images. Each image must already be publicly accessible over HTTP or HTTPS. |
| `num_images` | integer | No | Number of images to generate (1-8). |
| `resolution` | string ("720p" | "1600p") | No | Output quality. |
| `webhook_url` | string | No | Optional public HTTPS URL that receives the terminal completed, failed, or nsfw payload. |
| `aspect_ratio` | string ("1:1" | "4:3" | "3:4" | "3:2" | "2:3" | "16:9" | "9:16") | No | Aspect ratio of each generated image. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Seedance 2 Text Video

**Slug:** `HIGGSFIELD_GENERATE_SEEDANCE_2_TEXT_VIDEO`

Submit a ByteDance Seedance 2.0 text-to-video request through Higgsfield and return the request handle used to track the asynchronous result. Managed estimates above $2 are rejected before generation submission. No polling is performed; use the returned request ID with GET_REQUEST_STATUS. Managed generation charges the numeric provider estimate when submission is accepted, including if generation later fails. Managed requests cannot be canceled.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the video to generate. |
| `duration` | integer | No | Requested output duration in seconds (4-15). |
| `resolution` | string ("480p" | "720p" | "1080p" | "4k") | No | Output resolution tier. |
| `webhook_url` | string | No | Optional public HTTPS URL that receives the terminal completed, failed, or nsfw payload. |
| `aspect_ratio` | string ("16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9") | No | Output width-to-height ratio. |
| `generate_audio` | boolean | No | Whether to generate audio with the video. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Image

**Slug:** `HIGGSFIELD_GENERATE_SOUL_STANDARD_IMAGE`

Submit a text-to-image request to Higgsfield Soul Standard and return the request ID used to track the asynchronous result. Managed estimates above $2 are rejected before generation submission. No polling is performed; use the returned request ID with GET_REQUEST_STATUS. Managed generation charges the numeric provider estimate when submission is accepted, including if generation later fails. Managed requests cannot be canceled.

**Instant:** Supported on the latest version.

**Instant pricing:** Soul Standard image generation uses the provider estimate for the selected resolution and image count, up to $2 per request.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `seed` | integer | No | Optional deterministic generation seed (1-1000000). |
| `prompt` | string | Yes | Text description of the image to generate. |
| `style_id` | string | No | Identifier of a style supported by Soul Standard. |
| `batch_size` | integer ("1" | "4") | No | Number of output images. Soul Standard supports only 1 or 4. |
| `resolution` | string ("720p" | "1080p") | No | Output resolution. Use 720p or 1080p. |
| `webhook_url` | string | No | Optional public HTTPS URL that receives the terminal completed, failed, or nsfw payload. |
| `aspect_ratio` | string ("9:16" | "16:9" | "4:3" | "3:4" | "1:1" | "2:3" | "3:2") | No | Output width-to-height ratio. |
| `enhance_prompt` | boolean | No | Whether Higgsfield should enhance the prompt before generation. |
| `style_strength` | number | No | Strength of the selected style (0-1). |
| `custom_reference_id` | string | No | Optional identifier of a completed character reference owned by the account. |
| `image_reference_url` | string | No | Optional public image URL used to guide prompt enhancement. |
| `custom_reference_strength` | number | No | Strength of the character reference (0-1). Zero uses the selected style's default character strength. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Soul V2 Image

**Slug:** `HIGGSFIELD_GENERATE_SOUL_V2_IMAGE`

Submit a text-to-image request to Higgsfield Soul V2 and return the request ID used to track the asynchronous result. Managed estimates above $2 are rejected before generation submission. No polling is performed; use the returned request ID with GET_REQUEST_STATUS. Managed generation charges the numeric provider estimate when submission is accepted, including if generation later fails. Managed requests cannot be canceled.

**Instant:** Supported on the latest version.

**Instant pricing:** Image generation uses the provider estimate for the selected resolution and image count, up to $2 per request.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `seed` | integer | No | Optional deterministic generation seed (1-1000000). Omit to use a random seed. |
| `prompt` | string | Yes | Text description of the image to generate. |
| `style_id` | string | No | Identifier of a style supported by Soul V2. |
| `batch_size` | integer ("1" | "4") | No | Number of output images. Soul V2 supports only 1 or 4. |
| `resolution` | string ("720p" | "1080p") | No | Output resolution tier. |
| `webhook_url` | string | No | Optional public HTTPS URL that receives the terminal completed, failed, or nsfw payload. |
| `aspect_ratio` | string ("9:16" | "16:9" | "4:3" | "3:4" | "1:1" | "2:3" | "3:2") | No | Output width-to-height ratio. |
| `enhance_prompt` | boolean | No | Whether Higgsfield should enhance the prompt before generation. |
| `style_strength` | number | No | Strength of the selected style (0-1). This parameter currently has no effect on generation. |
| `custom_reference_id` | string | No | Optional identifier of a completed character reference owned by the account. |
| `custom_reference_strength` | number | No | Strength of the character reference (0-1). Must be greater than 0 when custom_reference_id is supplied. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate Video From Image

**Slug:** `HIGGSFIELD_GENERATE_VIDEO_FROM_IMAGE`

Generate a video from a publicly accessible starting image with Higgsfield DOP Lite and return the request ID used to track the asynchronous result. Managed estimates above $2 are rejected before generation submission. No polling is performed; use the returned request ID with GET_REQUEST_STATUS. Managed generation charges the numeric provider estimate when submission is accepted, including if generation later fails. Managed requests cannot be canceled.

**Instant:** Supported on the latest version.

**Instant pricing:** DOP Lite video generation uses the provider estimate, up to $2 per request.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `seed` | integer | No | Optional deterministic generation seed (1-1000000). |
| `prompt` | string | Yes | Text description of the desired motion and scene. |
| `image_url` | string | Yes | Public HTTP or HTTPS URL of the first-frame image to animate. The image must already be publicly accessible. |
| `webhook_url` | string | No | Optional public HTTPS URL that receives the terminal completed, failed, or nsfw payload. |
| `end_image_url` | string | No | Optional public HTTP or HTTPS URL of the desired final frame. The image must already be publicly accessible. |
| `enhance_prompt` | boolean | No | Whether Higgsfield should enhance the prompt before generation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Character Reference

**Slug:** `HIGGSFIELD_GET_CHARACTER_REFERENCE`

Get a Higgsfield Soul ID character reference and its current training status by ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | Character-reference UUID returned by CREATE_CHARACTER_REFERENCE. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Request Status

**Slug:** `HIGGSFIELD_GET_REQUEST_STATUS`

Get the current state of a Higgsfield generation request and return generated image, video, or audio URLs when complete.

**Instant:** Supported on the latest version.

**Instant pricing:** $0 per request

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | Generation request ID returned by a Higgsfield generation action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List SOUL V2 Styles

**Slug:** `HIGGSFIELD_LIST_SOUL_V2_STYLES`

List the SOUL V2 image styles available to the authenticated Higgsfield account, including the style IDs accepted by SOUL V2 generation requests.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |