# Higgsfield AI API

> Provider: **Higgsfield**
> Source: https://www.pixazo.ai/models/higgsfield

Advanced AI capabilities for image and video generation.

## Higgsfield 1.0

### Text to Image

## Base URL

```
https://gateway.pixazo.ai/ai-model-api/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Generate Soul Request - AI Model API

## Request Code

HTTP Python JavaScript cURL

```
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
import json

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())
```

```
const url = 'https://gateway.pixazo.ai/ai-model-api/v1/generateSoul';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};

const 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'
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.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"
}'
```

## Output

```
{
  "request_id": "ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=ai-model-api&operation=generate-image)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Generate Soul Request

Parameter

Required

Type

Description

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

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

```
{
  "request_id": "ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_SUBSCRIPTION\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'ai-model-api' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "ai-model-api",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ai-model-api",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ai-model-api_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.

### Image to Video

## Base URL

```
https://gateway.pixazo.ai/ai-model-api/v1
```

## Authentication

All requests require an API key passed via header.

Header

Type

Required

Description

Ocp-Apim-Subscription-Key

string

Yes

Your API subscription key

## Image To Video Request - AI Model API

## Request Code

HTTP Python JavaScript cURL

```
POST https://gateway.pixazo.ai/ai-model-api/v1/generateImageToVideoRequest
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "model": "dop-lite",
  "prompt": "A serene lake with gentle ripples, birds flying overhead, cinematic lighting",
  "seed": 123456,
  "motions_id": "[MOTION_ID]",
  "motions_strength": 0.7,
  "input_images": ["https://example.com/images/lake-scene.jpg"],
  "enhance_prompt": true
}
```

```
import requests

url = "https://gateway.pixazo.ai/ai-model-api/v1/generateImageToVideoRequest"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "model": "dop-lite",
    "prompt": "A serene lake with gentle ripples, birds flying overhead, cinematic lighting",
    "seed": 123456,
    "motions_id": "[MOTION_ID]",
    "motions_strength": 0.7,
    "input_images": ["https://example.com/images/lake-scene.jpg"],
    "enhance_prompt": True
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

```
const url = 'https://gateway.pixazo.ai/ai-model-api/v1/generateImageToVideoRequest';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
  model: 'dop-lite',
  prompt: 'A serene lake with gentle ripples, birds flying overhead, cinematic lighting',
  seed: 123456,
  motions_id: '[MOTION_ID]',
  motions_strength: 0.7,
  input_images: ['https://example.com/images/lake-scene.jpg'],
  enhance_prompt: true
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

```
curl -X POST "https://gateway.pixazo.ai/ai-model-api/v1/generateImageToVideoRequest" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
--data-raw '{
  "model": "dop-lite",
  "prompt": "A serene lake with gentle ripples, birds flying overhead, cinematic lighting",
  "seed": 123456,
  "motions_id": "[MOTION_ID]",
  "motions_strength": 0.7,
  "input_images": ["https://example.com/images/lake-scene.jpg"],
  "enhance_prompt": true
}'
```

## Output

```
{
  "request_id": "ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

[Try Now](https://api.pixazo.ai/api-details#api=ai-model-api&operation=image-to-video-request)

## Webhook (Optional)

Add the `X-Webhook-URL` header to your generate request to receive a POST callback instead of polling.

```
X-Webhook-URL: https://your-server.com/webhook/callback
```

## Request Parameters - Image To Video Request

Field

Type

Required

Default

Description

model

enum string

Yes

—

The image-to-video model to use for generation. Available options: `dop-lite`, `dop-preview`, `dop-turbo`. Each model offers different quality and speed trade-offs. Example: `dop-lite`

prompt

string

Yes

—

Text description/prompt for video generation. Describes the desired video content, style, and motion. Be descriptive for better results. Example: `A peaceful sunset over mountains with clouds moving slowly`

seed

integer

Yes

—

Random seed for reproducible results. Must be between 1 and 1,000,000. Using the same seed with identical parameters will produce similar results. Example: `500000`

motions\_id

string (UUID)

Yes

—

Unique identifier for the motion preset. This ID corresponds to predefined motion effects available in the system. You can get motion\_id using the API: https://endpoints.appypie.com/api-details#api=ai-model-api-polling&operation=motions

motions\_strength

number (0-1)

Yes

—

Intensity of the motion effect application. Range from 0.0 (minimal effect) to 1.0 (maximum effect) with 0.01 step precision. Higher values create more pronounced motion. Example: `0.75`

input\_images

array of strings

Yes

—

Array of image URLs for video generation. Each URL must be a publicly accessible link pointing to a valid image file. Supported formats include JPEG, PNG, WebP. Must contain exactly 1 element for standard generation. Example: `["https://example.com/image1.jpg"]`

input\_images\_end

array of strings

No

null

Array of end frame image URLs for Start & End Frame functionality. Each URL must be a publicly accessible link pointing to a valid image file. Supported formats include JPEG, PNG, WebP. Minimum length: 1 element. Enables advanced frame interpolation between start and end images. Example: `["https://example.com/end-frame.jpg"]`

enhance\_prompt

boolean

Yes

—

Whether to automatically enhance and refine the provided prompt. When `true`, the system will optimize your prompt for better video generation results. Example: `true`

check\_nsfw

boolean

No

true

Whether to perform NSFW (Not Safe For Work) content detection. When `true`, the system will check for inappropriate content and may reject the request if detected.

## Minimum Request

```
{
  "model": "dop-lite",
  "prompt": "A serene lake with gentle ripples, birds flying overhead, cinematic lighting",
  "seed": 123456,
  "motions_id": "[MOTION_ID]",
  "motions_strength": 0.7,
  "input_images": ["https://example.com/images/lake-scene.jpg"],
  "enhance_prompt": true
}
```

## Full Request (all options)

```
{
  "model": "dop-lite",
  "prompt": "A serene lake with gentle ripples, birds flying overhead, cinematic lighting",
  "seed": 123456,
  "motions_id": "[MOTION_ID]",
  "motions_strength": 0.7,
  "input_images": ["https://example.com/images/lake-scene.jpg"],
  "input_images_end": ["https://example.com/images/lake-end-frame.jpg"],
  "enhance_prompt": true,
  "check_nsfw": true
}
```

## Response

```
{
  "request_id": "ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

## Request Headers

Header

Value

Content-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

Your API subscription key

## Response Handling

Common status codes for Image To Video Request.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

Too Many Requests

500

Internal Server Error

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal Server Error

## Error Responses

Queue system errors and model validation errors.

### Queue System Errors

```
// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
```

```
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'ai-model-api' not found or is disabled"
}
```

### Error via Status/Webhook

```
{
  "request_id": "ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "ai-model-api",
  "error": "Description of the error",
  "output": null
}
```

## Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

### Endpoint

```
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
```

## cURL Example

```
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

## Response (Completed)

```
{
  "request_id": "ai-model-api_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ai-model-api",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ai-model-api_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}
```

## Response Fields

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string|null

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

Status

Description

QUEUED

Request accepted, waiting to be processed

PROCESSING

Being processed by the model

COMPLETED

Done — output contains the result

FAILED

Failed — check error field

ERROR

System error — not charged

## Status Flow

```
QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR
```

## Typical Workflow

1.  **Send a generate request** to the API endpoint
2.  **Save the `request_id`** from the response
3.  **Poll** every 5-10 seconds: `GET /v2/requests/status/{request_id}`
4.  **When `status` is `"COMPLETED"`**, download from `output.media_url`

**Tip:** Use `X-Webhook-URL` header to get a callback instead of polling.