Higgsfield Soul API
Higgsfield Soul is a high-aesthetic AI photo & video model that delivers fashion-grade realism with a vast library of style presets, enabling creators to produce editorial visuals without needing a camera.
Higgsfield Soul API Documentation
Generate Soul Request - Request Code
POST https://gateway.pixazo.ai/ai-model-api/v1/generateSoul Content-Type: application/json Cache-Control: no-cache Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY { "prompt": "Woman on rooftop", "soul_style_id": "a5f63c3b-70eb-4979-af5e-98c7ee1e18e8", "width_and_height": "1536x1152", "image_reference_type": "image_url", "image_reference_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png" }import requests url = "https://gateway.pixazo.ai/ai-model-api/v1/generateSoul" headers = { "Content-Type": "application/json", "Cache-Control": "no-cache", "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY" } data = { "prompt": "Woman on rooftop", "soul_style_id": "a5f63c3b-70eb-4979-af5e-98c7ee1e18e8", "width_and_height": "1536x1152", "image_reference_type": "image_url", "image_reference_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png" } response = requests.post(url, headers=headers, json=data) print(response.json())fetch('https://gateway.pixazo.ai/ai-model-api/v1/generateSoul', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY' }, body: JSON.stringify({ "prompt": "Woman on rooftop", "soul_style_id": "a5f63c3b-70eb-4979-af5e-98c7ee1e18e8", "width_and_height": "1536x1152", "image_reference_type": "image_url", "image_reference_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png" }) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error('Error:', error));curl -v -X POST "https://gateway.pixazo.ai/ai-model-api/v1/generateSoul" \ -H "Content-Type: application/json" \ -H "Cache-Control: no-cache" \ -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \ --data-raw '{ "prompt": "Woman on rooftop", "soul_style_id": "a5f63c3b-70eb-4979-af5e-98c7ee1e18e8", "width_and_height": "1536x1152", "image_reference_type": "image_url", "image_reference_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png" }'import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public class ApiExample { public static void main(String[] args) throws Exception { String url = "https://gateway.pixazo.ai/ai-model-api/v1/generateSoul"; String jsonBody = """ { "prompt": "Woman on rooftop", "soul_style_id": "a5f63c3b-70eb-4979-af5e-98c7ee1e18e8", "width_and_height": "1536x1152", "image_reference_type": "image_url", "image_reference_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png" } """; HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("Content-Type", "application/json") .header("Cache-Control", "no-cache") .header("Ocp-Apim-Subscription-Key", "YOUR_SUBSCRIPTION_KEY") .POST(HttpRequest.BodyPublishers.ofString(jsonBody)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } <?php $url = 'https://gateway.pixazo.ai/ai-model-api/v1/generateSoul'; $data = [ 'prompt' => 'Woman on rooftop', 'soul_style_id' => 'a5f63c3b-70eb-4979-af5e-98c7ee1e18e8', 'width_and_height' => '1536x1152', 'image_reference_type' => 'image_url', 'image_reference_image_url' => 'https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png' ]; $jsonData = json_encode($data); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type: application/json', 'Cache-Control: no-cache', 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' ]); $response = curl_exec($ch); curl_close($ch); echo $response; ?>Output
Successful API response:
{ "type": "text2image_soul", "created_at": "2025-09-17T08:40:11.428533Z", "jobs": [{ "id": "2f25c926-eb7e-4d1f-855f-bf297c69219c", "status": "queued" }], "job_set_id": "62d118c0-0251-4cf1-a765-4114e0a59d69" }Request Body - Generate Soul Request
Parameters for /generateSoul:
| Parameter | Required | Type | Description |
|---|---|---|---|
| webhook_url | No | string (URI) | The URL endpoint where callback requests will be sent. Must be a valid, accessible URI that can receive POST requests. If provided, `webhook_secret` is also required. Example: `https://your-domain.com/webhook` |
| webhook_secret | No | string | Secret key used for verifying callback authenticity. Use this to validate that callbacks are genuinely from Higgsfield. Required if `webhook_url` is provided. Example: `webhook_secret_abc123` |
| prompt | Yes | string | Text description for image generation. Describes the desired image content, style, and visual characteristics. Be descriptive for better results. Example: `A serene mountain landscape at sunset with golden light` |
| width_and_height | Yes | enum string | Desired width and height of output image. Available options: `1152x2048`, `2048x1152`, `2048x1536`, `1536x2048`, `1344x2016`, `2016x1344`, `960x1696`, `1536x1536`, `1536x1152`, `1696x960`, `1152x1536`, `1088x1632`, `1632x1088`. Example: `1152x2048` |
| enhance_prompt | No | boolean | Whether to automatically enhance and refine the provided prompt. When `true`, the system will optimize your prompt for better image generation results. Example: `true` |
| style_id | No | string (UUID) | Chosen preset for soul image generation. If null then General soul style is applied. Use `/getTextToImageGetSoulStyles` to get available style IDs. Example: `464ea177-8d40-4940-8d9d-b438bab269c7`. Get some other style using the API: https://endpoints.appypie.com/api-details#api=ai-model-api-polling&operation=soul-styles |
| style_strength | No | number | Strength of the style application. Range from 0.0 (minimal style) to 1.0 (maximum style) with 0.01 step precision. Higher values create more pronounced artistic effects. Example: `0.8` |
| quality | No | enum string | Output image quality. Available options: `720p`, `1080p`. Higher quality takes longer to generate but produces better results. Example: `1080p` |
| seed | No | integer | null | Seed for reproducibility. If null then random seed is applied. Must be between 1 and 1,000,000. Using the same seed with identical parameters will produce similar results. Example: `500000` |
| custom_reference_id | No | string (UUID) | null | The ID of a character that has already been created. Use this to generate images in a specific character's style. Example: `3c90c3cc-0d44-4b50-8888-8dd25736052a` |
| custom_reference_strength | No | number | Strength of the custom reference application. Range from 0.0 (minimal effect) to 1.0 (maximum effect) with 0.01 step precision. Example: `0.9` |
| image_reference_type | No | string | Type of the image reference. Must be `image_url`. Required if `image_reference_image_url` is provided. Example: `image_url` |
| image_reference_image_url | No | string (URI) | URL of an image to be used as a source for image generation. Must be a valid URI with length between 1-2083 characters. Required if `image_reference_type` is provided. Example: `https://example.com/reference-image.jpg` |
| batch_size | No | enum integer | Number of images to generate in a single batch. Available options: `1`, `4`. Higher batch sizes take longer but can be more cost-effective. Example: `4` |
Example Request - Generate Soul Request
JSON
{ "prompt": "Woman on rooftop", "soul_style_id": "a5f63c3b-70eb-4979-af5e-98c7ee1e18e8", "width_and_height": "1536x1152", "image_reference_type": "image_url", "image_reference_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/model.png" }Response - Generate Soul Request
JSON
{ "type": "text2image_soul", "created_at": "2025-09-17T08:40:11.428533Z", "jobs": [ { "id": "2f25c926-eb7e-4d1f-855f-bf297c69219c", "job_set_type": "text2image_soul", "status": "queued", "results": null } ], "input_params": { "prompt": "A beautiful landscape with mountains and lakes", "width": 1536, "height": 1152, "enhance_prompt": true, "style_id": "464ea177-8d40-4940-8d9d-b438bab269c7", "style_strength": 1, "seed": 832591, "custom_reference": null, "custom_reference_strength": 1, "image_reference": { "id": "59fb894d-9578-440e-8627-b964176c47b3", "type": "media_input", "url": "https://d3snorpfx4xhv8.cloudfront.net/39a839b9-b17a-4494-bd4f-fa844dccb0df/59fb894d-9578-440e-8627-b964176c47b3.jpg" } }, "job_set_id": "62d118c0-0251-4cf1-a765-4114e0a59d69" }Request Headers
| Header | Description |
|---|---|
| Content-Type | application/json |
| Cache-Control | no-cache |
| Ocp-Apim-Subscription-Key | Your API subscription key for authentication |
Response Handling
The AI Model API returns specific HTTP status codes and response bodies to indicate the success or failure of a request. Developers should implement error handling in their applications to manage these responses effectively.
Common Status Codes and Responses
| Status Code | Description | Response Body |
|---|---|---|
| 200 | Success - The request was successfully processed. | { "success": true, ... } |
| 400 | Bad Request - The request contains invalid parameters or missing fields. | { "error": "Invalid request parameters" } |
| 401 | Unauthorized - The provided subscription key is missing or invalid. | { "error": "Invalid or missing authentication" } |
| 403 | Forbidden - The subscription does not have access to this API or action. | { "error": "Access denied for this operation" } |
| 404 | Not Found - The requested resource or endpoint could not be found. | { "error": "Endpoint not found" } |
| 429 | Too Many Requests - The request rate limit has been exceeded. | { "error": "Rate limit exceeded, please retry later" } |
| 500 | Internal Server Error - An unexpected error occurred on the server. | { "error": "An unexpected error occurred, please try again later" } |
Example Error Response
{ "error": "Invalid parameters" }Retrieving Image Result and URL
After submitting your request, use this endpoint to check status and retrieve results.
Endpoint
POST https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults
Request Body
{ "job_set_id": "62d118c0-0251-4cf1-a765-4114e0a59d69" }Code Examples
POST https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults Content-Type: application/json Cache-Control: no-cache Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY { "job_set_id": "62d118c0-0251-4cf1-a765-4114e0a59d69" }import requests url = "https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults" headers = { "Content-Type": "application/json", "Cache-Control": "no-cache", "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY" } data = { "job_set_id": "62d118c0-0251-4cf1-a765-4114e0a59d69" } response = requests.post(url, headers=headers, json=data) print(response.json())fetch('https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY' }, body: JSON.stringify({ "job_set_id": "62d118c0-0251-4cf1-a765-4114e0a59d69" }) }) .then(response => response.json()) .then(data => console.log(data)) .catch(error => console.error('Error:', error));curl -v -X POST "https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults" \ -H "Content-Type: application/json" \ -H "Cache-Control: no-cache" \ -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \ --data-raw '{ "job_set_id": "62d118c0-0251-4cf1-a765-4114e0a59d69" }'import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public class PollingExample { public static void main(String[] args) throws Exception { String url = "https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults"; String jsonBody = """ { "job_set_id": "62d118c0-0251-4cf1-a765-4114e0a59d69" } """; HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("Content-Type", "application/json") .header("Cache-Control", "no-cache") .header("Ocp-Apim-Subscription-Key", "YOUR_SUBSCRIPTION_KEY") .POST(HttpRequest.BodyPublishers.ofString(jsonBody)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } <?php $url = 'https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults'; $data = [ 'job_set_id' => '62d118c0-0251-4cf1-a765-4114e0a59d69' ]; $jsonData = json_encode($data); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type: application/json', 'Cache-Control: no-cache', 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' ]); $response = curl_exec($ch); curl_close($ch); echo $response; ?>Example Success Response
{ "id": "96ddb2c0-2685-XXXX-XXXX-XXXXXXXXXXXX", "type": "text2image_soul", "created_at": "2025-09-16T11:16:51.045020Z", "jobs": [{ "id": "182d2a3c-8bfd-XXXX-XXXX-XXXXXXXXXXXX", "job_set_type": "text2image_soul", "status": "completed", "results": { "min": { "url": "https://.../e902a82f-9fc2-XXXX-XXXX-XXXXXXXXXXXXXXXX_min.mp4", "type": "image" }, "raw": { "url": "https://.../e902a82f-9fc2-XXXX-XXXX-XXXXXXXXXXXXXXXX_min.mp4", "type": "image" } } }], "input_params": { "prompt": "<PROMPT>", "model": "<MODEL>", "seed": <SEED>, "motions": [{ "id": "<MOTION_ID>", "strength": <MOTION_STRENGTH> }], "input_images": [{ "type": "image_url", "image_url": "https://.../f7d959e1-4643-XXXX-XXXX-XXXXXXXXXXXX.png" }], "enhance_prompt": false, "check_nsfw": true } }Higgsfield Soul API Pricing
| Quality | Batch | Price (USD) |
|---|---|---|
| 720p | 1 | $0.15 |
| 720p | 4 | $0.19 |
| 1080p | 1 | $0.25 |
| 1080p | 4 | $0.37 |