Skip to main content

​
Overview

The Model endpoint is the primary entry point for generating content with the Higgsfield API. Each model on the Higgsfield platform has a unique model_id (e.g., higgsfield-ai/soul/standard). Base API URL: https://platform.higgsfield.ai The Higgsfield API uses an asynchronous request-response pattern. When you submit a generation request, it enters a queue and processes in the background. This approach offers several advantages:
  • Monitor task status without maintaining open connections
  • Cancel requests that haven’t started processing
  • Avoid resource-intensive concurrent connections

​
API Endpoints

​
Queue Management

EndpointMethodDescription
https://platform.higgsfield.ai/{model_id}POSTSubmit a generation request to the queue
https://platform.higgsfield.ai/requests/{request_id}/statusGETRetrieve the status of a generation request
https://platform.higgsfield.ai/requests/{request_id}/cancelPOSTCancel a pending request

​
Parameters

  • model_id: The unique identifier for the model (e.g., higgsfield-ai/soul/standard)
  • request_id: A unique UUID assigned to your request upon submission

​
Usage Examples

​
Submitting a Generation Request

curl -X POST 'https://platform.higgsfield.ai/higgsfield-ai/soul/standard' \
  --header 'Authorization: Key {your_api_key}:{your_api_key_secret}' \
  --data '{
    "prompt": "your prompt here",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

​
Response Format

​
Queued Request

{
  "status": "queued",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status_url": "https://platform.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
  "cancel_url": "https://platform.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
}

​
Completed Request

{
  "status": "completed",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status_url": "https://platform.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
  "cancel_url": "https://platform.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel",
  "images": [
    {
      "url": "https://image.url/example.jpg"
    }
  ],
  "video": {
    "url": "https://video.url/example.mp4"
  }
}

​
Request Statuses

StatusDescription
queuedRequest is waiting in the queue and has not started processing
in_progressGeneration is actively processing (cancellation not available)
nsfwContent failed moderation checks (credits refunded)
failedGeneration encountered an error (credits refunded)
completedGeneration finished successfully (media available for download)

​
Canceling a Request

You can cancel a request only while it remains in the queued status. Once processing begins, cancellation is no longer possible. 
curl -X POST https://platform.higgsfield.ai/requests/{request_id}/cancel \
  --header 'Authorization: Key {your_api_key}:{your_api_key_secret}'
If cancellation was successful, you will get a 202 Accepted response status code. Otherwise, response status code will be 400 Bad Request.

​
Best Practices

  • Poll the status endpoint periodically to check request progress
  • Or use webhooks to get generation result by HTTP
  • Store the request_id to retrieve results later
  • Handle different status codes appropriately in your application