Higgsfield

Higgsfield API

Asynchronous generative-media API. Submit a generation request to any of the 100+ model endpoints (POST /{model_id}), then retrieve status (GET /requests/{request_id}/status), cancel a queued request (POST /requests/{request_id}/cancel), or receive a webhook when the request reaches a final status (completed, failed, nsfw). Authenticated with an API key + secret via the "Authorization: Key {key}:{secret}" scheme.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.higgsfield.ai/docs
📖
APIReference
https://docs.higgsfield.ai/docs/how-to/introduction

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/higgsfield/refs/heads/main/openapi/higgsfield-openapi-original.json

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/higgsfield/refs/heads/main/overlays/higgsfield-openapi-overlay.yaml
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/higgsfield/refs/heads/main/apis.yml

OpenAPI Specification

higgsfield-openapi-original.json Raw ↑ 
{
    "info": {
        "title": "API Reference"
    },
    "servers": [
        {
            "url": "https://platform.higgsfield.ai"
        }
    ],
    "securitySchemes": {
        "authKey": {
            "type": "apiKey",
            "in": "header",
            "name": "Authorization",
            "description": "{api_key_id}:{api_key_secret}"
        }
    },
    "x-mcp": {
      "enabled": true
    },
    "paths": {
        "/requests/{request_id}/status": {
            "get": {
                "summary": "Get Generation Status",
                "operationId": "get_request_status",
                "parameters": [
                    {
                        "name": "request_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid",
                            "title": "Request Id"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "$ref": "#/components/schemas/RequestStatus"
                    }
                }
            }
        },
        "/requests/{request_id}/cancel": {
            "post": {
                "summary": "Get Generation Status",
                "operationId": "get_request_status",
                "parameters": [
                    {
                        "name": "request_id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid",
                            "title": "Request Id"
                        }
                    }
                ],
                "responses": {
                    "202": {
                        "description": "Successful Response"
                    }
                }
            }
        },
        "/higgsfield-ai/dop/turbo": {
            "post": {
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "seed": {
                                        "type": "integer",
                                        "title": "Seed",
                                        "default": null,
                                        "maximum": 1000000,
                                        "minimum": 1
                                    },
                                    "prompt": {
                                        "type": "string",
                                        "title": "Prompt"
                                    },
                                    "motions": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "#/definitions/MotionSchema"
                                        },
                                        "title": "Motions",
                                        "default": null,
                                        "maxItems": 2,
                                        "minItems": 0
                                    },
                                    "image_url": {
                                        "type": "string",
                                        "title": "First frame image",
                                        "format": "uri"
                                    },
                                    "end_image_url": {
                                        "type": "string",
                                        "title": "Last frame image",
                                        "format": "uri"
                                    },
                                    "enhance_prompt": {
                                        "type": "boolean",
                                        "title": "Enhance Prompt",
                                        "default": true
                                    }
                                },
                                "required": [
                                    "prompt",
                                    "image_url"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The request status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RequestStatus"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/higgsfield-ai/dop/lite": {
            "post": {
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "seed": {
                                        "type": "integer",
                                        "title": "Seed",
                                        "default": null,
                                        "maximum": 1000000,
                                        "minimum": 1
                                    },
                                    "prompt": {
                                        "type": "string",
                                        "title": "Prompt"
                                    },
                                    "motions": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "#/definitions/MotionSchema"
                                        },
                                        "title": "Motions",
                                        "default": null,
                                        "maxItems": 2,
                                        "minItems": 0
                                    },
                                    "image_url": {
                                        "type": "string",
                                        "title": "First frame image",
                                        "format": "uri"
                                    },
                                    "end_image_url": {
                                        "type": "string",
                                        "title": "Last frame image",
                                        "format": "uri"
                                    },
                                    "enhance_prompt": {
                                        "type": "boolean",
                                        "title": "Enhance Prompt",
                                        "default": true
                                    }
                                },
                                "required": [
                                    "prompt",
                                    "image_url"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The request status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RequestStatus"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/higgsfield-ai/dop/standard": {
            "post": {
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "seed": {
                                        "type": "integer",
                                        "title": "Seed",
                                        "default": null,
                                        "maximum": 1000000,
                                        "minimum": 1
                                    },
                                    "prompt": {
                                        "type": "string",
                                        "title": "Prompt"
                                    },
                                    "motions": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "#/definitions/MotionSchema"
                                        },
                                        "title": "Motions",
                                        "default": null,
                                        "maxItems": 2,
                                        "minItems": 0
                                    },
                                    "image_url": {
                                        "type": "string",
                                        "title": "First frame image",
                                        "format": "uri"
                                    },
                                    "end_image_url": {
                                        "type": "string",
                                        "title": "Last frame image",
                                        "format": "uri"
                                    },
                                    "enhance_prompt": {
                                        "type": "boolean",
                                        "title": "Enhance Prompt",
                                        "default": true
                                    }
                                },
                                "required": [
                                    "prompt",
                                    "image_url"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The request status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RequestStatus"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/higgsfield-ai/popcorn/auto": {
            "post": {
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "seed": {
                                        "type": "integer",
                                        "title": "Seed",
                                        "default": null,
                                        "maximum": 1000000,
                                        "minimum": 1
                                    },
                                    "prompt": {
                                        "type": "string",
                                        "title": "Prompt"
                                    },
                                    "image_urls": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "title": "Reference image",
                                            "format": "uri"
                                        },
                                        "title": "Image references",
                                        "maxItems": 8,
                                        "minItems": 0
                                    },
                                    "num_images": {
                                        "type": "integer",
                                        "title": "Output images count",
                                        "default": 1,
                                        "maximum": 8,
                                        "minimum": 1
                                    },
                                    "resolution": {
                                        "enum": [
                                            "720p",
                                            "1600p"
                                        ],
                                        "type": "string",
                                        "title": "Quality",
                                        "default": "720p"
                                    },
                                    "aspect_ratio": {
                                        "enum": [
                                            "1:1",
                                            "4:3",
                                            "3:4",
                                            "3:2",
                                            "2:3",
                                            "16:9",
                                            "9:16"
                                        ],
                                        "type": "string",
                                        "title": "Aspect Ratio",
                                        "default": "4:3"
                                    }
                                },
                                "required": [
                                    "prompt"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The request status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RequestStatus"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/higgsfield-ai/soul/character": {
            "post": {
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "seed": {
                                        "type": "integer",
                                        "title": "Seed",
                                        "default": null,
                                        "maximum": 1000000,
                                        "minimum": 1
                                    },
                                    "prompt": {
                                        "type": "string",
                                        "title": "Prompt"
                                    },
                                    "style_id": {
                                        "type": "string",
                                        "title": "Soul Style",
                                        "format": "uuid",
                                        "default": null
                                    },
                                    "batch_size": {
                                        "enum": [
                                            1,
                                            4
                                        ],
                                        "type": "integer",
                                        "title": "Result images",
                                        "default": 1
                                    },
                                    "resolution": {
                                        "enum": [
                                            "720p",
                                            "1080p"
                                        ],
                                        "type": "string",
                                        "title": "Resolution",
                                        "default": "720p"
                                    },
                                    "aspect_ratio": {
                                        "enum": [
                                            "9:16",
                                            "16:9",
                                            "4:3",
                                            "3:4",
                                            "1:1",
                                            "2:3",
                                            "3:2"
                                        ],
                                        "type": "string",
                                        "title": "Aspect Ratio",
                                        "default": "4:3"
                                    },
                                    "enhance_prompt": {
                                        "type": "boolean",
                                        "title": "Enhance Prompt",
                                        "default": true
                                    },
                                    "style_strength": {
                                        "type": "number",
                                        "title": "Style strength",
                                        "format": "float",
                                        "default": 1,
                                        "maximum": 1,
                                        "minimum": 0
                                    },
                                    "custom_reference_id": {
                                        "type": "string",
                                        "title": "Character ID",
                                        "format": "uuid"
                                    },
                                    "image_reference_url": {
                                        "type": "string",
                                        "title": "Image reference url",
                                        "format": "uri"
                                    },
                                    "custom_reference_strength": {
                                        "type": "number",
                                        "title": "Character strength",
                                        "format": "float",
                                        "default": 1,
                                        "maximum": 1,
                                        "minimum": 0
                                    }
                                },
                                "required": [
                                    "prompt",
                                    "custom_reference_id",
                                    "custom_reference_strength"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The request status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RequestStatus"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/higgsfield-ai/soul/reference": {
            "post": {
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "seed": {
                                        "type": "integer",
                                        "title": "Seed",
                                        "default": null,
                                        "maximum": 1000000,
                                        "minimum": 1
                                    },
                                    "prompt": {
                                        "type": "string",
                                        "title": "Prompt"
                                    },
                                    "style_id": {
                                        "type": "string",
                                        "title": "Soul Style",
                                        "format": "uuid",
                                        "default": null
                                    },
                                    "batch_size": {
                                        "enum": [
                                            1,
                                            4
                                        ],
                                        "type": "integer",
                                        "title": "Result images",
                                        "default": 1
                                    },
                                    "resolution": {
                                        "enum": [
                                            "720p",
                                            "1080p"
                                        ],
                                        "type": "string",
                                        "title": "Resolution",
                                        "default": "720p"
                                    },
                                    "aspect_ratio": {
                                        "enum": [
                                            "9:16",
                                            "16:9",
                                            "4:3",
                                            "3:4",
                                            "1:1",
                                            "2:3",
                                            "3:2"
                                        ],
                                        "type": "string",
                                        "title": "Aspect Ratio",
                                        "default": "4:3"
                                    },
                                    "enhance_prompt": {
                                        "type": "boolean",
                                        "title": "Enhance Prompt",
                                        "default": true
                                    },
                                    "style_strength": {
                                        "type": "number",
                                        "title": "Style strength",
                                        "format": "float",
                                        "default": 1,
                                        "maximum": 1,
                                        "minimum": 0
                                    },
                                    "image_reference_url": {
                                        "type": "string",
                                        "title": "Image reference url",
                                        "format": "uri"
                                    }
                                },
                                "required": [
                                    "prompt",
                                    "image_reference_url"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The request status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RequestStatus"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/higgsfield-ai/soul/standard": {
            "post": {
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "seed": {
                                        "type": "integer",
                                        "title": "Seed",
                                        "default": null,
                                        "maximum": 1000000,
                                        "minimum": 1
                                    },
                                    "prompt": {
                                        "type": "string",
                                        "title": "Prompt"
                                    },
                                    "style_id": {
                                        "type": "string",
                                        "title": "Soul Style",
                                        "format": "uuid",
                                        "default": null
                                    },
                                    "batch_size": {
                                        "enum": [
                                            1,
                                            4
                                        ],
                                        "type": "integer",
                                        "title": "Result images",
                                        "default": 1
                                    },
                                    "resolution": {
                                        "enum": [
                                            "720p",
                                            "1080p"
                                        ],
                                        "type": "string",
                                        "title": "Resolution",
                                        "default": "720p"
                                    },
                                    "aspect_ratio": {
                                        "enum": [
                                            "9:16",
                                            "16:9",
                                            "4:3",
                                            "3:4",
                                            "1:1",
                                            "2:3",
                                            "3:2"
                                        ],
                                        "type": "string",
                                        "title": "Aspect Ratio",
                                        "default": "4:3"
                                    },
                                    "enhance_prompt": {
                                        "type": "boolean",
                                        "title": "Enhance Prompt",
                                        "default": true
                                    },
                                    "style_strength": {
                                        "type": "number",
                                        "title": "Style strength",
                                        "format": "float",
                                        "default": 1,
                                        "maximum": 1,
                                        "minimum": 0
                                    }
                                },
                                "required": [
                                    "prompt"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The request status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RequestStatus"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/veo3.1": {
            "post": {
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "prompt": {
                                        "type": "string",
                                        "title": "Prompt"
                                    },
                                    "duration": {
                                        "enum": [
                                            "4",
                                            "6",
                                            "8"
                                        ],
                                        "type": "string",
                                        "title": "Duration",
                                        "default": "6"
                                    },
                                    "resolution": {
                                        "enum": [
                                            "720",
                                            "1080"
                                        ],
                                        "type": "string",
                                        "title": "Resolution",
                                        "default": "720"
                                    },
                                    "aspect_ratio": {
                                        "enum": [
                                            "16:9",
                                            "9:16"
                                        ],
                                        "type": "string",
                                        "title": "Aspect Ratio",
                                        "default": "16:9"
                                    },
                                    "generate_audio": {
                                        "type": "boolean",
                                        "title": "Generate audio",
                                        "default": false
                                    }
                                },
                                "required": [
                                    "prompt",
                                    "aspect_ratio",
                                    "resolution",
                                    "generate_audio"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The request status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RequestStatus"
                              

# --- truncated at 32 KB (143 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/higgsfield/refs/heads/main/openapi/higgsfield-openapi-original.json