Soul ID — API reference | Higgsfield API

Soul ID creates and manages a custom reference from input images. Use the custom-reference endpoints below to create a Soul ID, check its processing status, list existing Soul IDs, or delete one.

1. Calling the API

Base URL: https://api.higgsfield.ai.

Method	Endpoint	Operation
POST	`/v1/custom-references`	Create a Soul ID
GET	`/v1/custom-references/list`	List Soul IDs
GET	`/v1/custom-references/{reference_id}`	Get a Soul ID and its status
DELETE	`/v1/custom-references/{reference_id}`	Delete a Soul ID

Setup

Keep credentials on the server and load them from environment variables. Replace the example image URL with a URL accessible to the API.

export HF_API_KEY_ID="YOUR_API_KEY_ID"
export HF_API_KEY_SECRET="YOUR_API_KEY_SECRET"

Python examples use requests:

JavaScript examples use the built-in fetch API in a server environment.

2. Authentication

The endpoint definitions specify these headers:

Header	Required by the schema	Value
`hf-api-key`	Yes	API key ID (UUID)
`hf-secret`	No	API key secret

The examples send both credentials. Also send Content-Type: application/json when creating a Soul ID.

JavaScript setup

Run this setup before the JavaScript examples:

const baseUrl = "https://api.higgsfield.ai";
const headers = {
  "hf-api-key": process.env.HF_API_KEY_ID,
  "hf-secret": process.env.HF_API_KEY_SECRET,
};

Python setup

Run this setup before the Python examples:

import os
import requests

base_url = "https://api.higgsfield.ai"
headers = {
    "hf-api-key": os.environ["HF_API_KEY_ID"],
    "hf-secret": os.environ["HF_API_KEY_SECRET"],
}

3. Create a Soul ID

POST /v1/custom-references

Request parameters

Parameter	Type	Required	Constraints
`name`	string	Yes	Maximum 100 characters
`input_images`	array of objects	Yes	Between 1 and 100 images
`input_images[].type`	string	Yes	Must be `image_url`
`input_images[].image_url`	string	Yes	Image URL

Create examples

const response = await fetch(`${baseUrl}/v1/custom-references`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
  "name": "My Soul ID",
  "input_images": [
    {
      "type": "image_url",
      "image_url": "https://example.com/portrait.jpg"
    }
  ]
}),
});
if (!response.ok) throw new Error(await response.text());
const soulId = await response.json();
const referenceId = soulId.id;

Create response

A successful creation returns HTTP 200 with a Soul ID object. Save its id as reference_id for subsequent requests.

Field	Type	Description
`id`	UUID string	Soul ID identifier
`name`	string	Reference name
`created_at`	date-time string	Creation time
`status`	string	Processing status; schema default is `not_ready`
`thumbnail_url`	string or null	Reference thumbnail
`in_progress_at`	date-time string or null	Processing start time

4. Get a Soul ID and check status

GET /v1/custom-references/{reference_id}

Use the UUID from the creation response. Processing is asynchronous: repeat this GET request at intervals until status is completed or failed.

Status values

Status	Meaning
`not_ready`	Not ready for processing
`queued`	Queued for processing
`in_progress`	Processing is in progress
`completed`	Processing completed
`failed`	Processing failed

Get examples

const referenceId = "YOUR_REFERENCE_ID";
const response = await fetch(
  `${baseUrl}/v1/custom-references/${referenceId}`,
  { headers },
);
if (!response.ok) throw new Error(await response.text());
const soulId = await response.json();
console.log(soulId.status, soulId.reference_media);

Get response

HTTP 200 returns the Soul ID fields described above and reference_media, an array of objects with id (UUID) and media_url (string).

5. List Soul IDs

GET /v1/custom-references/list

Query parameters

Parameter	Type	Required	Default
`page`	integer	No	`1`
`page_size`	integer	No	`20`

List examples

const response = await fetch(
  `${baseUrl}/v1/custom-references/list?page=1&page_size=20`,
  { headers },
);
if (!response.ok) throw new Error(await response.text());
const page = await response.json();
console.log(page.items, page.total_pages);

List response

HTTP 200 returns total, page, page_size, total_pages, and items. Each item contains a Soul ID object with the fields listed in the creation response.

6. Delete a Soul ID

DELETE /v1/custom-references/{reference_id}

Use the UUID of the Soul ID to delete.

Delete examples

const referenceId = "YOUR_REFERENCE_ID";
const response = await fetch(
  `${baseUrl}/v1/custom-references/${referenceId}`,
  { method: "DELETE", headers },
);
if (!response.ok) throw new Error(await response.text());
// HTTP 204 has no JSON response body.

Delete response

Successful deletion returns HTTP 204 with no response body.

7. Validation errors

The endpoint definitions document HTTP 422 for validation errors. Check the JSON body, required headers, path UUID, and query parameters against the schemas above.