# Higgsfield AI API

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

Advanced AI capabilities for image and video generation.

## Higgsfield 1.0

### 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.