Skip to content

Commit e5afd35

Browse files
myxamediyarclaude
myxamediyar
and
claude
committed
feat(higgsfield): add Higgsfield integration
Add a Higgsfield block for image and video generation: - Generate with any model endpoint, or a typed SOUL image operation - Get status, cancel, and delete generation requests - Create, get, list, and delete Soul ID characters Generation waits for completion by polling request status, with an option to return the request ID immediately. Credentials are a saved token service account (KEY_ID:KEY_SECRET), verified by listing the account's characters. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent d27970a commit e5afd35

35 files changed

Lines changed: 1999 additions & 6 deletions

‎apps/docs/components/icons.tsx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,19 @@ export function GaugeIcon(props: GaugeIconProps) {
2727
)
2828
}
2929

30+
interface HiggsfieldIconProps extends SVGProps<SVGSVGElement> {}
31+
32+
export function HiggsfieldIcon(props: HiggsfieldIconProps) {
33+
return (
34+
<svg {...props} viewBox='66 74 390 368' fill='none' xmlns='http://www.w3.org/2000/svg'>
35+
<path
36+
d='M419.055 253.911L418.753 250.505C415.893 217.823 395.28 156.334 338.099 156.334C295.668 156.334 263.614 199.548 235.326 237.647C212.754 268.158 193.196 294.333 171.676 294.333C165.956 293.715 158.585 290.771 154.073 284.112C150.009 278.069 148.957 270.326 151.062 261.032C154.37 246.318 173.332 232.688 193.343 218.129C204.325 210.386 215.613 202.176 223.438 194.278C246.011 171.82 257.446 155.557 257.446 129.383C257.446 103.21 243.453 90.196 231.716 84.62C208.242 73.471 173.785 79.976 151.817 99.494C148.508 102.593 145.195 105.532 142.185 108.32C120.065 128.611 105.17 142.397 71.012 131.861V174.298C116.304 194.899 154.375 155.557 168.821 137.437C179.954 125.512 191.691 118.541 200.421 118.541H200.874C204.787 118.696 208.095 120.246 210.506 123.034C214.419 127.683 215.924 133.104 215.169 139.142C213.513 151.845 200.723 166.71 177.249 182.974C149.712 202.025 103.669 233.931 100.055 274.046C97.346 302.857 111.792 331.664 134.364 342.813C187.028 368.523 219.082 324.227 253.085 277.452C279.117 241.364 303.795 207.136 338.103 207.136C368.949 207.136 380.385 233.465 380.385 250.039V253.294L377.375 253.911C302.591 267.542 261.812 339.718 261.812 373.016C261.812 406.317 289.198 434.817 322.903 434.817C362.328 434.817 411.079 400.122 418.905 302.546L419.207 298.986H450.354V253.915L419.055 253.911ZM378.276 303.936C372.259 362.326 343.215 389.588 325.611 389.588C317.636 389.588 306.504 382.771 306.504 370.073C306.504 355.826 327.117 312.612 373.462 299.758L378.879 298.364L378.276 303.936Z'
37+
fill='currentColor'
38+
/>
39+
</svg>
40+
)
41+
}
42+
3043
export function EnrichmentIcon(props: SVGProps<SVGSVGElement>) {
3144
return (
3245
<svg

‎apps/docs/components/ui/icon-mapping.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,7 @@ import {
140140
HarmonicIcon,
141141
HelpScoutIcon,
142142
HexIcon,
143+
HiggsfieldIcon,
143144
HubspotIcon,
144145
HuggingFaceIcon,
145146
HumanInTheLoopIcon,
@@ -475,6 +476,7 @@ export const blockTypeToIconMap: Record<string, IconComponent> = {
475476
harmonic: HarmonicIcon,
476477
helpscout: HelpScoutIcon,
477478
hex: HexIcon,
479+
higgsfield: HiggsfieldIcon,
478480
hubspot: HubspotIcon,
479481
huggingface: HuggingFaceIcon,
480482
human_in_the_loop: HumanInTheLoopIcon,

‎apps/docs/content/docs/integrations/higgsfield.mdx‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,295 @@
1+
---
2+
title: Higgsfield
3+
description: Generate images and videos with Higgsfield models
4+
integration:
5+
type: "higgsfield"
6+
color: "#D1FE17"
7+
---
8+
9+
import { ReferenceDetails } from "@/components/ui/reference-details"
10+
11+
12+
{/* MANUAL-CONTENT-START:intro */}
13+
[Higgsfield](https://higgsfield.ai) is an image and video generation platform with its own SOUL image models and hosted models from other providers, such as Kling, Seedance, Wan, and MiniMax.
14+
15+
With the Higgsfield block, you can:
16+
17+
- **Generate media with any model**: Send a model endpoint ID and that model's documented JSON input, then get back image, video, or audio URLs.
18+
- **Generate SOUL images**: Set aspect ratio, resolution, style, and a trained character without writing JSON.
19+
- **Train characters**: Create, check, list, and delete Soul ID characters from reference photo URLs to keep a person or mascot consistent across images.
20+
- **Manage requests**: Check the status of a request, cancel one that is still queued, or delete a finished request's data.
21+
22+
Create an API key in the [Higgsfield Console](https://console.higgsfield.ai), then connect it as a saved Higgsfield account in Sim. Paste the key ID and secret joined by a colon: `KEY_ID:KEY_SECRET`.
23+
24+
Generation runs in the background. By default the block waits for the result. Turn off **Wait for Result** to return the request ID right away, then use **Get Request Status** later. Output URLs expire after seven days by default, so copy media you need to keep. Which models you can use depends on your Higgsfield account; find endpoint IDs and their input fields in the [model catalog](https://docs.higgsfield.ai/docs/models).
25+
26+
In Sim, the Higgsfield block lets your agents produce product videos, ad creatives, and on-brand character images from a brief or a table of products.
27+
{/* MANUAL-CONTENT-END */}
28+
29+
## Use the block [#usage-instructions]
30+
31+
Generate images and videos with any Higgsfield model, create SOUL images with styles and trained characters, train and manage Soul ID characters, and check, cancel, or delete generation requests.
32+
33+
## Actions
34+
35+
### Higgsfield Generate
36+
37+
Submit a generation request to any Higgsfield image or video model endpoint with that model's documented JSON input, then wait for the output URLs.
38+
39+
<ReferenceDetails>
40+
41+
#### Input
42+
43+
| Parameter | Type | Required | Description |
44+
| --------- | ---- | -------- | ----------- |
45+
| `model` | string | Yes | Model endpoint ID from the Higgsfield model catalog, e.g. kling-video/v2.5-turbo/pro/text-to-video |
46+
| `input` | json | Yes | JSON request body documented for the model endpoint, e.g. \{"prompt": "...", "duration": 5\} |
47+
| `waitForCompletion` | boolean | No | Wait until the request finishes and return its output URLs. When false, return the request ID immediately. |
48+
| `webhookUrl` | string | No | HTTPS endpoint that Higgsfield notifies when the request finishes |
49+
| `idempotencyKey` | string | No | Key that makes retries return the original request instead of creating a duplicate \(1–255 visible ASCII characters\) |
50+
| `expiresAfter` | number | No | Seconds to keep the request data after it finishes, from 3600 up to the account retention |
51+
52+
#### Output
53+
54+
| Parameter | Type | Description |
55+
| --------- | ---- | ----------- |
56+
| `requestId` | string | Higgsfield request ID |
57+
| `status` | string | Request status: queued, in_progress, completed, failed, nsfw, or canceled |
58+
| `error` | string | Failure reason, when provided |
59+
| `imageUrls` | array | Generated image URLs \(image models\) |
60+
| `videoUrl` | string | Generated video URL \(video models\) |
61+
| `audioUrl` | string | Generated audio URL \(audio output\) |
62+
| `audioUrls` | array | Generated audio URLs \(audio output\) |
63+
| `statusUrl` | string | URL for checking the request status |
64+
| `cancelUrl` | string | URL for canceling the queued request |
65+
| `expiresAt` | string | When the output files are deleted and their URLs stop working |
66+
67+
</ReferenceDetails>
68+
69+
### Higgsfield Generate SOUL Image
70+
71+
Generate images with Higgsfield SOUL, optionally in a style or as a trained Soul ID character, then wait for the image URLs.
72+
73+
<ReferenceDetails>
74+
75+
#### Input
76+
77+
| Parameter | Type | Required | Description |
78+
| --------- | ---- | -------- | ----------- |
79+
| `prompt` | string | Yes | Text description of the image |
80+
| `aspectRatio` | string | No | Aspect ratio: 9:16, 16:9, 4:3, 3:4, 1:1, 2:3, or 3:2 \(default 4:3\) |
81+
| `resolution` | string | No | Resolution: 720p or 1080p \(default 720p\) |
82+
| `batchSize` | number | No | Number of images: 1 or 4 \(default 1\) |
83+
| `styleId` | string | No | SOUL style UUID \(defaults to the general style\) |
84+
| `styleStrength` | number | No | Style strength from 0 to 1 \(default 1\) |
85+
| `characterId` | string | No | Completed Soul ID character reference ID \(model version v1\) owned by the account |
86+
| `characterStrength` | number | No | Character strength from 0 to 1; 0 uses the style's default \(default 1\) |
87+
| `imageReferenceUrl` | string | No | Public image URL that guides prompt enhancement |
88+
| `enhancePrompt` | boolean | No | Let Higgsfield enhance the prompt \(default false\) |
89+
| `seed` | number | No | Seed from 1 to 1000000 for repeatable results |
90+
| `waitForCompletion` | boolean | No | Wait until the request finishes and return its output URLs. When false, return the request ID immediately. |
91+
| `webhookUrl` | string | No | HTTPS endpoint that Higgsfield notifies when the request finishes |
92+
| `idempotencyKey` | string | No | Key that makes retries return the original request instead of creating a duplicate \(1–255 visible ASCII characters\) |
93+
| `expiresAfter` | number | No | Seconds to keep the request data after it finishes, from 3600 up to the account retention |
94+
95+
#### Output
96+
97+
| Parameter | Type | Description |
98+
| --------- | ---- | ----------- |
99+
| `requestId` | string | Higgsfield request ID |
100+
| `status` | string | Request status: queued, in_progress, completed, failed, nsfw, or canceled |
101+
| `error` | string | Failure reason, when provided |
102+
| `imageUrls` | array | Generated image URLs \(image models\) |
103+
| `videoUrl` | string | Generated video URL \(video models\) |
104+
| `audioUrl` | string | Generated audio URL \(audio output\) |
105+
| `audioUrls` | array | Generated audio URLs \(audio output\) |
106+
| `statusUrl` | string | URL for checking the request status |
107+
| `cancelUrl` | string | URL for canceling the queued request |
108+
| `expiresAt` | string | When the output files are deleted and their URLs stop working |
109+
110+
</ReferenceDetails>
111+
112+
### Higgsfield Get Request Status
113+
114+
Get the status of a Higgsfield generation request and, once completed, its output URLs.
115+
116+
<ReferenceDetails>
117+
118+
#### Input
119+
120+
| Parameter | Type | Required | Description |
121+
| --------- | ---- | -------- | ----------- |
122+
| `requestId` | string | Yes | Higgsfield request ID returned by a generation request |
123+
124+
#### Output
125+
126+
| Parameter | Type | Description |
127+
| --------- | ---- | ----------- |
128+
| `requestId` | string | Higgsfield request ID |
129+
| `status` | string | Request status: queued, in_progress, completed, failed, nsfw, or canceled |
130+
| `error` | string | Failure reason, when provided |
131+
| `imageUrls` | array | Generated image URLs \(image models\) |
132+
| `videoUrl` | string | Generated video URL \(video models\) |
133+
| `audioUrl` | string | Generated audio URL \(audio output\) |
134+
| `audioUrls` | array | Generated audio URLs \(audio output\) |
135+
| `statusUrl` | string | URL for checking the request status |
136+
| `cancelUrl` | string | URL for canceling the queued request |
137+
| `expiresAt` | string | When the output files are deleted and their URLs stop working |
138+
139+
</ReferenceDetails>
140+
141+
### Higgsfield Cancel Request
142+
143+
Cancel a Higgsfield generation request that is still queued. Requests that have started processing cannot be canceled.
144+
145+
<ReferenceDetails>
146+
147+
#### Input
148+
149+
| Parameter | Type | Required | Description |
150+
| --------- | ---- | -------- | ----------- |
151+
| `requestId` | string | Yes | Higgsfield request ID to cancel |
152+
153+
#### Output
154+
155+
| Parameter | Type | Description |
156+
| --------- | ---- | ----------- |
157+
| `requestId` | string | ID of the canceled request |
158+
| `canceled` | boolean | Whether the request was canceled |
159+
160+
</ReferenceDetails>
161+
162+
### Higgsfield Delete Request
163+
164+
Immediately delete a finished Higgsfield request's output files, prompt, and parameters.
165+
166+
<ReferenceDetails>
167+
168+
#### Input
169+
170+
| Parameter | Type | Required | Description |
171+
| --------- | ---- | -------- | ----------- |
172+
| `requestId` | string | Yes | ID of a finished Higgsfield request |
173+
174+
#### Output
175+
176+
| Parameter | Type | Description |
177+
| --------- | ---- | ----------- |
178+
| `requestId` | string | ID of the deleted request |
179+
| `deleted` | boolean | Whether the request data was deleted |
180+
181+
</ReferenceDetails>
182+
183+
### Higgsfield Create Character
184+
185+
Train a reusable Soul ID character from public reference image URLs. Training runs in the background; use Get Character to check when it completes.
186+
187+
<ReferenceDetails>
188+
189+
#### Input
190+
191+
| Parameter | Type | Required | Description |
192+
| --------- | ---- | -------- | ----------- |
193+
| `name` | string | Yes | Character name \(up to 100 characters\) |
194+
| `modelVersion` | string | No | SOUL family that will use the character: v1, v2, or cinema \(default v1\) |
195+
| `imageUrls` | array | Yes | 1 to 100 public URLs of reference photos of the character |
196+
197+
#### Output
198+
199+
| Parameter | Type | Description |
200+
| --------- | ---- | ----------- |
201+
| `character` | json | Created character reference |
202+
| ↳ `id` | string | Character \(Soul ID\) reference ID |
203+
| ↳ `name` | string | Character name |
204+
| ↳ `modelVersion` | string | SOUL family: v1, v2, or cinema |
205+
| ↳ `status` | string | Training status: not_ready, queued, in_progress, completed, or failed |
206+
| ↳ `thumbnailUrl` | string | Thumbnail image URL |
207+
| ↳ `createdAt` | string | Creation timestamp |
208+
| ↳ `inProgressAt` | string | Training start timestamp |
209+
| ↳ `failReason` | string | Training failure reason |
210+
211+
</ReferenceDetails>
212+
213+
### Higgsfield Get Character
214+
215+
Get a Soul ID character reference, including its training status.
216+
217+
<ReferenceDetails>
218+
219+
#### Input
220+
221+
| Parameter | Type | Required | Description |
222+
| --------- | ---- | -------- | ----------- |
223+
| `characterId` | string | Yes | Soul ID character reference ID |
224+
225+
#### Output
226+
227+
| Parameter | Type | Description |
228+
| --------- | ---- | ----------- |
229+
| `character` | json | Character reference |
230+
| ↳ `id` | string | Character \(Soul ID\) reference ID |
231+
| ↳ `name` | string | Character name |
232+
| ↳ `modelVersion` | string | SOUL family: v1, v2, or cinema |
233+
| ↳ `status` | string | Training status: not_ready, queued, in_progress, completed, or failed |
234+
| ↳ `thumbnailUrl` | string | Thumbnail image URL |
235+
| ↳ `createdAt` | string | Creation timestamp |
236+
| ↳ `inProgressAt` | string | Training start timestamp |
237+
| ↳ `failReason` | string | Training failure reason |
238+
239+
</ReferenceDetails>
240+
241+
### Higgsfield List Characters
242+
243+
List the Soul ID character references in the Higgsfield account, one page at a time.
244+
245+
<ReferenceDetails>
246+
247+
#### Input
248+
249+
| Parameter | Type | Required | Description |
250+
| --------- | ---- | -------- | ----------- |
251+
| `page` | number | No | Page number, starting at 1 \(default 1\) |
252+
| `pageSize` | number | No | Characters per page \(default 20\) |
253+
254+
#### Output
255+
256+
| Parameter | Type | Description |
257+
| --------- | ---- | ----------- |
258+
| `characters` | array | Character references on this page |
259+
| ↳ `id` | string | Character \(Soul ID\) reference ID |
260+
| ↳ `name` | string | Character name |
261+
| ↳ `modelVersion` | string | SOUL family: v1, v2, or cinema |
262+
| ↳ `status` | string | Training status: not_ready, queued, in_progress, completed, or failed |
263+
| ↳ `thumbnailUrl` | string | Thumbnail image URL |
264+
| ↳ `createdAt` | string | Creation timestamp |
265+
| ↳ `inProgressAt` | string | Training start timestamp |
266+
| ↳ `failReason` | string | Training failure reason |
267+
| `total` | number | Total number of characters |
268+
| `page` | number | Current page number |
269+
| `pageSize` | number | Characters per page |
270+
| `totalPages` | number | Total number of pages |
271+
272+
</ReferenceDetails>
273+
274+
### Higgsfield Delete Character
275+
276+
Permanently delete a Soul ID character reference.
277+
278+
<ReferenceDetails>
279+
280+
#### Input
281+
282+
| Parameter | Type | Required | Description |
283+
| --------- | ---- | -------- | ----------- |
284+
| `characterId` | string | Yes | Soul ID character reference ID to delete |
285+
286+
#### Output
287+
288+
| Parameter | Type | Description |
289+
| --------- | ---- | ----------- |
290+
| `characterId` | string | ID of the deleted character |
291+
| `deleted` | boolean | Whether the character was deleted |
292+
293+
</ReferenceDetails>
294+
295+

‎apps/docs/content/docs/integrations/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,7 @@
123123
"harmonic",
124124
"helpscout",
125125
"hex",
126+
"higgsfield",
126127
"hubspot",
127128
"hubspot-service-account",
128129
"hubspot-setup",

0 commit comments

Comments
 (0)